Celestin Apprentice 2/Apprentice-Release2.iso/Source Code/C/Games/Xconq 7.0d16/doc/refman.texi

Text File | 1993-12-20 | 181.0 KB | 5,571 lines | [TEXT/MPS ]

@node Reference Manual,,,

@chapter Reference Manual

This manual is the complete description of GDL.
The style is somewhat terse; for more detail on how to
use GDL to design games, see Chapter 3.

Symbols followed by @code{??} have not been implemented yet,
so they should be considered as subject to change.

@section Language Syntax

GDL resembles Lisp, but instead of defining functions,
the contents of a file declare
certain objects (such as units and unit types) to exist
and specify their content.
In other words, GDL is @emph{nonprocedural}.
This means that most of the time, you can list the various
forms in any order you like.
The main restriction is that any symbol, such as a variable
or the name of a type, has to be defined before it is used.
Also, forms such as @code{set} and @code{add}, that set the
value of a variable or property,
always overwrite the previous data irreversibly,
so ordering of these is very important.

@subsection Lexical Elements

Numbers are introduced by a decimal digit, plus, or minus signs.
They may contain only decimal digits, a decimal point, and be followed
(immediately, no whitespace allowed)
by a percent sign or a recognized unit of measure.

Strings are sequences of characters enclosed by doublequotes (@code{"}).
They may contain any character except ASCII NUL (@code{'\0'}).
To include a doublequote, use backslash, as in @code{"a \"quoted\" string"}.
To include a nonprinting or eight-bit character,
use backslash followed by three octal
digits, which will be interpreted as an eight-bit character code.
(This is mostly the same syntax as in C.)
Note that game design files may be passed over networks
and between different kinds of computer systems,
so non-ASCII characters should not be inserted verbatim into strings.

Symbols are sequences of characters that don't
include any of the other special characters.  If you wish to include such
characters in a symbol, enclose it in vertical bars,
for example @code{|foo bar|}.
(The bars are not part of the symbol.)
Symbols are case-sensitive,
but this will be changed eventually.

Lists are a sequence of expressions enclosed in parentheses.
The empty list is either @code{nil} or @code{()}.
``Dotted pairs'' are not allowed.
Anything that is not a list is an @dfn{atom}.

All of these objects may range up to a very large size.
(You may still run into bugs if you make strings or symbols
over about 100 chars in length.)

Comments are enclosed either within @code{#| |#} (which nests properly,
like Common Lisp and unlike C), or else extend from a semicolon
@code{;} to the end of the line.  A comment is equivalent to whitespace,
so @code{(a#|bcd|#e)} is the same as @code{(a e)}.

[@code{#} by itself is a special token]

True/false values
are just the integers 0 and 1, with no special characteristics.

@deffn GlobalConstant @code{true}
@end deffn
@deffn GlobalConstant @code{false}
These constants are symbolic forms for @code{1} and @code{0}.
They are identical to numbers,
but more descriptive for parameters that are boolean-valued.
@end deffn

Unit, material, and terrain types are distinct objects.

@subsection Conventions Used

Descriptions of values in this manual follow the conventions listed here.

For parameters described as @var{t/f},
both @code{1}, @code{0} and @code{true}, @code{false} may be used.
Parameters described as @var{n} and @var{n%} are numbers.
Parameters described as @var{dist} or @var{length}
are also numbers, but are in the unit of measure for lengths.
Parameters described as @var{str} or @var{string} are strings.

Parameters described as
@var{u} or @var{ui}, @var{m} or @var{mi}, and @var{t} or @var{ti},
are values that must be unit, material, or terrain types, respectively.

Parameters described as @var{utype-value-list} match unit types with values.
They can have several forms:

@itemize
@item
@code{(n1 n2 ...)} matches @code{n1} with type 0, etc in order.
@item
@code{((u1 n1) (u2 n2) ...)} evaluates @code{u1} to get a unit type,
then matches it with @code{n1}.  @code{u1} etc may also be a list of
types, in which case all the types get matched with @code{n1}.
@end itemize

Other types of lists, such as those defined as @var{side-value-list},
are interpreted similarly.

@subsection Forms and Evaluation

A @dfn{form} is either any single expression that appears in the file.
A GDL file consists of a sequence of forms.
Most forms of interest will be lists.
whose first element is a symbol identifying the form.
For instance, a form beginning with the symbol @code{side}
declares a side object.
When the file containing such a form is read, @i{Xconq} will
create a side object and fill in any properties as specified by the form.
(Properties are like properties or attributes - most kinds of objects
have some.)

In most contexts, @i{Xconq} will @dfn{evaluate} an expression
before using it, such as when filling in an object's property.
Numbers and strings evaluate to themselves, while symbols
evaluate to their bindings.
Lists evaluate to the same list, but with all the elements
evaluated.

@subsection Tables

A @dfn{table} is a two-dimensional array of values indexed by types.
Indices can be any pair of unit, material, or terrain type.
The set of tables is fixed by @i{Xconq}, and all are described below.

@deffn Form @code{table} table-name items@dots{}
This is the general form to fill in a table.
The table named by @var{table-name} is filled in from the @var{items}.
If an item is an atom, then every position in the
table is filled in with that item, overwriting any
previously-specified values.
If an item is a list, it must be a three-element list
of the form @code{(@var{type1} @var{type2} @var{value})}.
If both @var{type1} and @var{type2} are single types,
then @var{value} will be put into the table at the position
indexed by the two types.
If one of @var{type1} or @var{type2} evaluates to a list,
@i{Xconq} will iterate over all members of the list while
keeping the other type constant,
while if both @var{type1} and @var{type2} are lists,
then @i{Xconq} will iterate over all pairs from the two lists.
The values used during iteration depend on whether the @var{value}
is a list.  If @var{value} is an atom, then that value will just
be used on every iteration.  If a list, then @i{Xconq} will
use successive elements of the list while iterating.
@end deffn

The following forms are all equivalent:
@example
(table foo (a y 1) (b y 2) (c y 3) (a z 9) (b z 9) (c z 9))

(table foo ((a b c) y (1 2 3)) ((a b c) (z) 9))

(define v1 (a b c))
(table foo (v1 y (1 2 3)) (v1 z 9))

(table foo ((a b c) (y z) ((1 2 3) (9 9 9))))
@end example

@subsection Modifying Objects

Since forms normally define or create new objects,
GDL defines the @code{add} form to modify existing objects.

@deffn Form @code{add} objects property new-values@dots{}
This form evaluates the atom or list @var{objects} to arrive at the
set of objects to be modified.
Then it uses the @var{new-values} to write new data into
the property named @var{property} of those objects.
The @var{new-values} may be a single number or string, or a list.

If @var{objects} is the symbol @code{table}, then this form adds
to a table instead.
@end deffn

@subsection Symbols

Most of the symbols used in a game module are the predefined ones
described in this manual.
Others are attached to types when the types are defined,
and still others name objects like units and sides.
You can also define and set your own symbols to arbitrary values.

@deffn Form @code{define} symbol value
This form defines the symbol @var{symbol} to be bound to the
result of evaluating @var{value}.
If @var{symbol} is already defined, @i{Xconq} will warn about it,
and ignore this form.
@end deffn

@deffn Form @code{set} symbol value
This form rebinds the already-bound symbol @var{symbol}
to be bound to the result of evaluating @var{value}.
If @var{symbol} is @emph{not} bound already,
then @i{Xconq} will warn about it, but proceed anyway.
@end deffn

@deffn Form @code{undefine} symbol
This form destroys any binding of the @var{symbol}.
This is allowed for any symbol, including already-unbound symbols.
@end deffn

@subsection Lists

@deffn Operation @code{quote} xxx@dots{}
This operation prevents any evaluation of @var{xxx}.
@end deffn

@deffn Operation @code{list} xxx@dots{}
This operation makes a list out of all the @var{xxx}.
@end deffn

@deffn Operation @code{append} xxx@dots{}
This operation appends all the @var{xxx} (which may be
lists or not) into a single list.  Non-lists will appear
as though they were single-element lists.
@end deffn

@deffn Operation @code{remove} list1 list2
This operation removes the members of @var{list1} from @var{list2}.
@end deffn

@section Game Modules

The game module declaration supplies information about the file as a whole.
It is optional; if missing, @i{Xconq} will get the module's
name from its file name, and supply defaults for the other properties.

@deffn Form @code{game-module} [name] properties@dots{}
This form defines the properties of this game module.
The optional @var{name} is a string that will be used to look up
the module in libraries.
If the @var{name} is supplied, then this form is considered to be the
definition of the module, and overwrites any
@code{game-module} form previously appearing in this file.
If @var{name} is missing, then this form will modify the
existing description of the module.
@end deffn

@deffn ModuleProperty @code{title} string
If defined, this property is the name by which the module will be displayed to
players.  It is not used internally, so the name can be modified freely
(unlike the module's name, which may appear in other modules).
Defaults to the module's name.
@end deffn

@deffn ModuleProperty @code{blurb} string
This property is a one-line description that users will see when they
are deciding whether to play the module.
It will be displayed without any modification:
@example
Welcome to my nightmare! (version 1.0 with stronger goblins)
@end example
Defaults to @code{""}.
@end deffn

@deffn ModuleProperty @code{picture-name} string
This property is the name of a picture that may be displayed along
with the module's blurb, by those interfaces that support such pictures.
Defaults to @code{""}.
@end deffn

@deffn ModuleProperty @code{base-game} t/f
@end deffn

@deffn ModuleProperty @code{instructions} strings@dots{}
This property is a list of strings that are the instructions on how to play
the game.  Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{notes} strings@dots{}
This property is a list of strings comprising the set of
detailed player's notes for the module.
Both the list and each string in the list can be of any length.
When displayed, the strings are all concatenated together, so the division
into strings here is just for convenience.
How these are displayed is up to the interface, but in general an empty
string signals a new paragraph.
Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{design-notes} strings@dots{}
This property is a list of strings that are notes addressed to game designers.
Defaults to @code{()}.
@end deffn

@deffn ModuleProperty @code{version} string
This property is the version of the module.
Defaults to @code{""},
which indicates that the module's version is undefined.
@end deffn

@deffn ModuleProperty @code{program-version} versions
This property dentifies @i{Xconq} versions for which this module
is appropriate.
If specified, then players will get a warning if they attempt to use this
module with an inappropriate version of @i{Xconq}.
Possible forms include a string, which allows the module only for
exactly matching version of @i{Xconq},
and @code{(@var{comparison} @var{version})},
which allows versions satisfying the @var{comparison} test,
which may only be @code{>=} or @code{<=}.
So for instance
@example
(game-module "foo" (program-version (>= "7.0.3")))
@end example
is claimed to only work for versions 7.0.3 or later.
Defaults to @code{""}, which means that the module is appropriate for
any version of @i{Xconq}.

Notes that the @code{program-version} is strictly a heuristic to forewarn
players; in practice it can be very difficult to know which modules work
with which programs.  (The problems are similar to those encountered
by programmers using different compiler versions on their programs.)
@end deffn

@deffn ModuleProperty @code{variants} items@dots{}
This property defines named variants on this module.
Variants appear as startup options for the game.
The items have the form @code{([@var{name}] @var{type} [@var{data}])}.
The @var{name} is a string or symbol used to identify the choice to
the players, the @var{type} says what sort of change is being enabled,
and @var{data} supplies a range of values or content.
The different types of variants are listed below.
A game module may specify any number of variants.
Defaults to @code{()}.
@end deffn

@deffn VariantType @code{eval} forms
If this variant is chosen, execute the @var{forms}.
@end deffn

@deffn VariantType @code{number} [form sym [lo dflt hi]]
Replace occurrences of the symbol @var{sym} in @var{form}
to a value ranging between @var{lo} and @var{hi},
defaulting to @var{dflt},
then evaluate @var{form}.
@end deffn

@deffn VariantType @code{flag} variable dflt
@end deffn

@deffn VariantType @code{world-size} [width [height [circumference]]]
This variant allows players to choose the size of the world.
The sizes will default to the values in this variant's data.
(@var{width} and @var{height} can be lists of the form @code{(lo dflt hi)},
with the obvious interpretation??)
@end deffn

@deffn VariantType @code{world-seen} dflt
This variant allows players to choose whether
the terrain of the world will be known at the start of the game.
The default setting will be the value @code{dflt},
which may be either @code{true} or @code{false}.
@end deffn

@deffn VariantType @code{see-all} dflt
This variant allows players to choose whether everything will be seen
always, as with the global variable @code{see-all}.
The default is set by @code{dflt}.
@end deffn

@deffn ModuleProperty @code{base-module} name
This property is the name of a module that must be loaded first.
It is similar in effect to @code{include}.
@end deffn

@deffn ModuleProperty @code{default-base-module} name
This property specifies the name of a module that will be loaded
if this module is given as the ``top-level'' module,
such as via @code{-g} on a command line.

This is to prevent disasters when a library module that is
used only by other modules is instead loaded as if it were
a full game design.
@end deffn

@subsection Including Other Modules

You can include one game module in another.

@deffn Form @code{include} [if-needed] module-name [variant-settings]
This form has the effect of inserting the contents
of @var{module-name} into the current position in the module.
@code{game-module} forms in the included module are not inserted,
although they are remembered and may appear in displays.
@i{Xconq} will fail completely if the included module cannot be found.

Unlike C etc, the same module cannot be included more than once; you will
get a warning and the module will not be loaded.
@end deffn

Note that the module names are not file names,
so that system-specific features like directories and devices
cannot be included.
The mapping between module name and file name is interface-specific,
so if you want to distribute a module, you should make sure all the
module names don't have anything nonportable embedded.
Alphanumeric characters and hyphens are guaranteed to be portable.

@subsection Conditional Loading

[not really implemented yet - need a conditional stack, check matching
end, complain if no match - add do/skip flag to interp_form]

@deffn Form @code{if} sym test-form
@end deffn

@deffn Form @code{else} sym
@end deffn

@deffn Form @code{end-if} sym
@end deffn

@node World Design, Distances and Elevations, Language, Game Design

@section The World

The world consists of a set of @dfn{areas} (only one at present),
each of which is regular in shape and consists of a number of cells.
Each cell has a type of terrain and a number of optional pieces of data.
Each kind of per-cell data will be called a @dfn{layer} of the area.

@deffn Form @code{world} [circumference] properties@dots{}
This form defines the properties of the world as a whole.
@end deffn

@deffn WorldProperty @code{circumference} dist
This property is the distance around the entire world (as a sphere).
Default is @code{360}.
@end deffn

@deffn WorldProperty @code{axial-tilt} n
This property defines the extremes of seasonal changes.
@end deffn

@deffn Form @code{area} [width [height]] [restriction] properties@dots{}
This form defines the playing area of the world.
The @var{restriction} identifies how to get data for this area from
subsequent forms that are based on larger areas.
@end deffn

@deffn AreaRestriction @code{restrict} w h x y
This is a special form that specifies that subsequent layers in an
area of size w x h will be offset by x,y and then read into the
actual area.  [obscure explanation, see the library for examples]
@end deffn

@deffn AreaProperty @code{width} n
@end deffn
@deffn AreaProperty @code{height} n
These properties are the width and height of the world,
as measured in cells.
Allowable values range from 3x3
up to 32767x32767, which is one billion cells!
If only one of these is given, then the other defaults to the same value.
If neither has been given, then they default to @code{60} and @code{30},
respectively.
@end deffn

In the case of a cylinder, the world wraps around
in the x direction, and the width is the diameter of the cylinder,
while the height is just the
height in the usual sense.
A hexagon world is flat on the top and bottom; its width is
measured across the middle height, which is the largest span,
and height is the same
as for cylinders.  Here are some crude pictures, first of an 8x6 cylinder:
@example
# # # # # # # #
 : : + + : : : :
: : : + ^ : : :
 : : : : : : : :
: : : : ^ : : :
 # # # # # # # #
@end example

This world is an 8x7 hexagon:
@example
   # # # # #
  # : + + : #
 # : : + ^ : #
# : : + ^ : : #
 # : : : : : #
  # : : ^ : #
   # # # # #
@end example

There are two kinds of properties that an area may have:
scalar values such as latitude,
and layer values such as terrain and elevation.

@deffn AreaProperty @code{latitude} n
This property is the offset from the equator of the middle of the area
(height / 2).
Defaults to @code{0}.
@end deffn
@deffn AreaProperty @code{longitude} n
Defaults to @code{0}.
@end deffn

@subsection Layers

@dfn{Layers} constitute the bulk of data about an area of the world.
Each layer assigns a value to each cell in the area;
examples include cell terrain, temperatures, elevations, and so forth.
Since there may be many cells in a layer with the same values,
each layer uses a common run-length encoding scheme.
In this scheme, each horizontal band of cells
is a separate text string, and the contents of the string encode
individual numeric values, one for each cell.
The encoding uses the characters @code{a..~} and @code{:..[}
for 0 through 63,
and decimal digits followed by commas (or the end of the string)
for all other numbers.
Runs of constant value are prefixed with their length, in decimal.
Thus, the string
@example
"40adaa100,2*-99"
@end example
represents 46 values in all: 40 zeroes, a three, 2 more zeros, a 100,
and two -99s.
Although this format is totally unreadable,
it has the advantages of compactness and portability;
the expectation is that most layer editing will be done on-line.
Note that the run encoding is entirely optional.

The following subforms at the beginning of layer data have special effects:

@deffn LayerSubform @code{constant} n
This subform causes every value in the layer to be set to @var{n}.
@end deffn

@deffn LayerSubform @code{subarea} x y w h
This subform indicates that the layer data should be positioned at the given
rectangle in the layer.
@end deffn

@deffn LayerSubform @code{xform} mul add
This subform has the effect of first multiplying the raw value by @var{mul},
then adding @var{add} and storing the result into the layer.
@end deffn

@deffn LayerSubform @code{by-bits}
@end deffn

@deffn LayerSubform @code{by-char} str
This subform specifies that the characters in @var{str} give the
encodings of values in the layer.
The first character in @var{str} encodes 0, the second encodes 1,
and so forth.
@end deffn

@deffn LayerSubform @code{by-name} name-list
[what is the syntax of name-list exactly?]
This subform is for generic worlds that are useful across multiple game designs.
The value/name pairs allow for the matching of terrain types by name,
so that if, say,
the ``sea'' terrain type was type #0 in one game and type #4 in another,
the world would have sea in all the same places after it was read in.
In practice, only a few worlds are this general.
If a named terrain type is not present, @i{Xconq} will warn about it
and substitute type 0.
@end deffn

@deffn AreaProperty @code{terrain} layer-data@dots{}
This property is the actual layer of terrain types for cells.
@end deffn

@deffn AreaProperty @code{aux-terrain} terrain-type layer-data@dots{}
This property fills in values for borders, connections, and coatings.
For border and connection terrain,
the value is a six-bit number (0..63),
with a bit turned on in each direction that there is a border
or connection.
For coating types, the value is the depth of the coating.
@end deffn

@deffn AreaProperty @code{features} feature-list layer-data@dots{}
This property specifies the nature and location of all geographical features.
The @var{feature-list} is a list of lists, where each sublist has the form
@code{([@var{id}] @var{typename} @var{name} [@var{super}])}
where @var{id} is the numerical id referenced in the layer data
(defaults to feature's position in the @var{feature-list}),
@var{typename} is a symbol or string giving the general type of feature
(such as @code{bay}),
@var{name} is the name of the feature
(such as @code{"Bay of Bengal"}),
and @var{super} is the optional id of another feature that
incorporates this feature.
@end deffn

@deffn AreaProperty @code{material} material-type layer-data@dots{}
This property declares the quantity of the given @var{material-type}
in each cell of the area.
@end deffn

@deffn AreaProperty @code{people-sides} layer-data@dots{}
This property says which side the people of each cell are on.
A @var{side-encoding} of @code{exact} assigns 0 to independence (no side),
1 to the first side, and so forth; otherwise, the encoding is a list
of side names/ids and numbers.
@end deffn

@subsection Distances and Elevations

@deffn AreaProperty @code{elevations} layer-data@dots{}
This property is the world elevation data itself.
If any elevation falls outside the min/max elevation range
for the terrain type of the cell, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn

@deffn AreaProperty @code{cell-width} dist
This property is the distance across a single cell,
expressed as units of elevation.  Defaults to @code{1}.
[this *must* be a long...]
@end deffn

@subsection Temperatures

Each type of terrain has a temperature range in which it may be found.
Any calculation that would fall outside this range will be clipped.

The temperature can be set to have a given value at a given elevation.
All air temperatures will be interpolated appropriately.

@deffn GlobalVariable @code{temperature-floor} n
This variable is the lowest possible temperature.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{temperature-floor-elevation} n
This variable is the elevation at which the temperature is always at
@code{temperature-floor}.
Defaults to @code{0}.
@end deffn

@deffn AreaProperty @code{temperatures} layer-data@dots{}
This property contains the temperature data itself.
If any temperature falls outside the min/max temperature range, then it
will be truncated appropriately.
Defaults to @code{0} for each cell.
@end deffn

@subsection Winds

Winds are defined as having a nonnegative force and a direction.

@deffn AreaProperty @code{winds} layer-data@dots{}
This property contains the force and direction of the prevailing
winds in each cell.
@end deffn

@subsection Clouds

@deffn AreaProperty @code{clouds} layer-data@dots{}
@end deffn

@deffn AreaProperty @code{cloud-bottoms} layer-data@dots{}
@end deffn

@deffn AreaProperty @code{cloud-heights} layer-data@dots{}
@end deffn

@section Sides

@deffn Form @code{side} [id] properties@dots{}
This form has the effect of declaring a side to exist.
If the number or symbol @var{id} is supplied and
matches that of a side that has already been created,
then the properties will modify the pre-existing side.
Otherwise a new side object will be created,
with a arbitrarily-chosen numeric id ranging between 1 and @code{sides-max}.
If the given @var{id} is a symbol, then the side object will be
bound to that symbol.
@end deffn

@deffn GlobalVariable @code{sides-min} n
@end deffn
@deffn GlobalVariable @code{sides-max} n
These variables are the minimum and maximum number of sides that may exist in
a game.  Defaults are to @code{1} and the internal parameter @code{MAXSIDES},
which is usually around 7.
@code{MAXSIDES} can only be changed by recompiling @i{Xconq}.
@end deffn

@deffn Form @code{side-defaults} properties@dots{}
This form sets the defaults for all newly-created sides declared
subsequently.
These defaults will be set before the new side's properties are interpreted.
This form has no effect on existing sides or on side declarations that
modify existing sides.
@end deffn

@subsection Name and Related Properties

If the game design allows, all of these properties can be set at startup by
the players (see <side config> and below).
Omission of some of these results in suppression or substitution,
depending on the interface and the situation.
Omission of all name properties allows the side to go unmentioned,
which is useful when the concept of ``side'' is useless or
confusing to a player (as in some adventure games).
All of these properties may be set at any time by any player.

@deffn SideProperty @code{name} str
This property is the proper name of a side, as a country or alliance name.
Examples include @code{"Axis"} and @code{"Hyperborea"}.
Defaults to @code{""}.
@end deffn

@deffn SideProperty @code{long-name} str
This property is the long form of a side's name,
as in @code{"People's Republic of Hyperborea"}.
Defaults to be the same as the side's name.
@end deffn

@deffn SideProperty @code{short-name} str
This property is an short name or acronym for the side,
often just the letters of the long name, as in @code{"PRH"}.
Defaults to @code{""}.
@end deffn

@deffn SideProperty @code{noun} str
This property is the name of an individual unit or person
belonging to the side.
Defaults to @code{""}, which suppresses any mention of the side
when (textually) describing the individual.
@end deffn

@deffn SideProperty @code{plural-noun} str
This property is what you would call a group of individuals.
Defaults to the most common plural form of the @code{noun}
(in English, the default pluralizer adds an ``s''),
so any alternative plural noun, such as @code{"Chinese"},
will need an explicit @code{plural-noun} value.
@end deffn

@deffn SideProperty @code{adjective} str
This property is an adjective that can be used of individuals on the side,
as in @code{"Spanish"}.
Defaults to @code{""}, which suppresses use of the adjective.
@end deffn

As a complete example, a side named @code{"Poland"} would have a long name
@code{"Kingdom of Poland"}, short name @code{"Po"},
noun @code{"Pole"}, plural noun @code{"Poles"},
and adjective @code{"Polish"}.

@deffn SideProperty @code{color-scheme} str
@end deffn
@deffn SideProperty @code{colors} str
@end deffn
@deffn SideProperty @code{color} str
This property is a comma-separated list of colors that represents the side.
Defaults to @code{"black"}.  (The three forms are just synonyms.)
@end deffn

@deffn SideProperty @code{emblem-name} str
This property is the name of a graphical icon that represents the side.
An emblem name of @code{"none"} suppresses any emblem display for the side.
Defaults to @code{""}, which gives the side a randomly-selected emblem.
@end deffn

@deffn SideProperty @code{names-locked} t/f
If the value of this property is @code{true},
then the player cannot modify any of the side's names.
Defaults to @code{false}.
@end deffn

@subsection Side Class

@deffn SideProperty @code{class} str
This property is a side's class, which is a keyword that characterizes the side.
Any number of sides may be in the same class.
@end deffn

@subsection Status in Game

Once a side is in the game, it can never be totally removed.
However, sides can become inactive.

@deffn SideProperty @code{active} t/f
This property is @code{true} if the side is still actively participating in the game.
If the side has won, lost, or simply withdrew, this will be @code{false}.
Any units on a side not in the game are effectively frozen statues;
they don't do anything, and are untouchable by anyone else.
Defaults to @code{true}.
@end deffn

@deffn SideProperty @code{status} lose/draw/win
This property tells how this side did in the game.  Defaults to @code{draw}.
@end deffn

@deffn GlobalConstant @code{win}
@end deffn
@deffn GlobalConstant @code{draw}
@end deffn
@deffn GlobalConstant @code{lose}
These constants are the different possible values for a side's status.
@end deffn

@deffn SideProperty @code{advantage}
@end deffn
@deffn SideProperty @code{advantage-min}
@end deffn
@deffn SideProperty @code{advantage-max}
@end deffn

@subsection Side Relationships

By default, sides are neutral with respect to each other.

Control is a situation where one side
can observe and move another side's units, but not vice versa.
The controlling side can also just take the units of the controlled side.
If the controlled side loses or resigns, then the controlling side
automatically gets everything.
Both sides must agree to this relationship.

@deffn SideProperty @code{controlled-by} side
This property refers to the side controlling this one.
If 0, then the side is not under control.
Defaults to @code{0}.
@end deffn

The closest side relationship is one of trust.
A trusted side unit's may do anything at any time,
including entering and leaving units on the other side,
consuming the other side's materials, and so forth.

@deffn SideProperty @code{trusts} side-value-list
This property is true for any side that is trusted by this side.
Note that this relationship need not be symmetrical.
Defaults to @code{false} for all sides.
@end deffn

Note that these parameters apply only to relationships as enforced by
@i{Xconq}.  In an actual game, both human and robot sides can make agreements
and have positive/negative opinions about the other sides.

@deffn SideProperty @code{trades} side-value-list
This property defines the trading relationship with other sides.
@end deffn

@subsection Numbering Units

@deffn SideProperty @code{next-numbers} utype-value-list
This property gives the next serial numbers that will be assigned to units
acquired by this side.
Defaults to @code{1} for each unit type (Dijkstra notwithstanding,
that's still where people start numbering things).
@end deffn

If the unit is of a type that gets numbered
(@code{assign-number} property is true),
then any unit of that type, acquired by any means whatsoever,
will be assigned the @code{next-numbers} value for that type
and @code{next-numbers} will be incremented.

@subsection Side-Specific Namers

A side can have its own set of namers (see below)
that will be used for units
and geographical features associated with that side.

@deffn SideProperty @code{unit-namers} utype-value-list
This property specifies which namers will be used with which types
that the side starts out with or creates new units.
These will not be run automatically on captured units or gifts.
Defaults to @code{""} for each unit type.
@end deffn

@deffn SideProperty @code{feature-namers} feature-type-value-list
This property specifies which namers to use with which geographical
features in the side's initial country (if if has one).
Defaults to @code{()}.
@end deffn

@subsection Tech Levels

The tech level of a side determines what it can do with each type of unit.

@deffn SideProperty @code{tech} utype-value-list
This property assigns a tech level to each unit type named.
Defaults to @code{0} for each unit type.
@end deffn

@deffn SideProperty @code{init-tech} utype-value-list
This property is the tech level at the beginning of the current turn.
Defaults to @code{0} for each unit type.
@end deffn

@subsection Views

These properties are necessary only if the relevant globals
are set a certain way (@code{see-all} is false, etc).

@deffn SideProperty @code{terrain-view} layer-data@dots{}
This property is the side's current knowledge of the world's terrain.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{unit-view} layer-data@dots{}
This property is the side's current knowledge of the world.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{unit-view-dates} layer-data@dots{}
This property is the turn number at which the unit view data
in the corresponding cell of the @code{unit-view} was set.
Defaults to @code{()}.
@end deffn

@subsection Interaction

@deffn SideProperty @code{turn-time-used} seconds
This property is the number of (real) seconds
that this side has been moving units during the present turn.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{total-time-used} seconds
This property is the number of (real) seconds that
this side has been moving units during the course of the game.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{timeouts} n
This property is the number of ``time outs'' a side gets for the game.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{timeouts-used} n
This property is the number of ``time outs'' a side has already used up.
Defaults to @code{0}.
@end deffn

@deffn SideProperty @code{finished-turn} t/f
This property is true if the side has declared that it is finished moving
things during this turn.
Defaults to @code{false}.
@end deffn

@deffn SideProperty @code{willing-to-draw} t/f
This property is true if the side will go along
with any other side that wants to end the game.
Defaults to @code{false}.
@end deffn

@deffn SideProperty @code{ai} xxx
This property is information about the AI associated with a side.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{respect-neutrality} t/f
@end deffn

@deffn SideProperty @code{real-timeout} seconds
This property is the number of (real) seconds to wait before declaring the
side to be finished with this turn.
Defaults to @code{-1}, which waits forever.
@end deffn

@deffn SideProperty @code{real-time-used} seconds
This property is the total number of seconds used by this side already in the game.
@end deffn

@deffn SideProperty @code{task-limit}
This property is the maximum number of tasks a unit is allowed to stack up.
@end deffn

@subsection Doctrine

Doctrines are objects that units consult to decide about individual behavior.

@deffn SideProperty @code{doctrines} utype-property-groups@dots{}
This property is the side's unit-type-specific doctrine.
Each @var{utype-property-group} has the form
@code{(@var{unit-types} properties@dots{})}.
Defaults to @code{()}.
@end deffn

@deffn SideProperty @code{doctrines-locked} t/f
@end deffn

@deffn Form @code{doctrine} [id] properties@dots{}
This form creates a doctrine with the given id and properties.
@end deffn

@deffn DoctrineProperty @code{ever-ask-side} t/f
This property is the true if the unit may ask the player for what to do,
instead of picking some default activity.
@end deffn

@deffn DoctrineProperty @code{avoid-bad-terrain} n%
This property is the probability that the unit will not enter
unhealthy terrain, even if it delays meeting goals.
Unhealthy means higher attrition and accident probs, materials
consumed faster than replaced, slower movement.
Defaults to @code{0}.
@end deffn

@deffn DoctrineProperty @code{repair-at} n%
This property indicates that when the unit's hp is at @var{n%} of max,
make a plan to repair.
Defaults to @code{50}.
@end deffn

@deffn DoctrineProperty @code{resupply-at} n%
This property indicates that when the level of a
operationally-consumed material is at @var{n%}
of capacity, try to resupply.
Defaults to @code{50}.
@end deffn

@deffn DoctrineProperty @code{rearm-at} n%
This property indicates that when the level of a
combat-consumed material is at @var{n%}
of capacity, try to resupply.
Defaults to @code{50}.
@end deffn

@deffn DoctrineProperty @code{fill-percentage} n%
This property indicates that when a transport is waiting for occupants,
plan to wait until the number of occupants is this percentage of capacity.
Defaults to @code{80}.
@end deffn

@deffn DoctrineProperty @code{expendability} n
This property is the odds at which a unit will be willing to attack.
@end deffn

@deffn DoctrineProperty @code{locked} t/f
This property is true if the doctrine cannot be modified by the player.
Defaults to @code{false}.
@end deffn

@subsection Other

@deffn SideProperty @code{self-unit} unit
This property is the id of a unit that represents the side itself.
Defaults to @code{0}, which means that no unit represents the side.
See below for more details on self units.
@end deffn

@deffn SideProperty @code{priority} n
@end deffn

@deffn SideProperty @code{scores} list
@end deffn

@deffn Form @code{independent-units} properties@dots{}
Like the @code{side} form, but sets properties for independent units.
@end deffn

@deffn SideProperty @code{ui-prefs}
This property contains interface-specific data for the side.
This is mainly for preservation across game save/restores,
and its form is defined by the interface.
@end deffn

@section Players

Player objects are rarely necessary when building game designs;
they typically only appear in saved games,
in order to ensure that the same players get the same sides
upon restoration.

@deffn SideProperty @code{player} id
This property is the unique identifier of a player that is running this side.
Defaults to @code{0}, which means that no player has been assigned
to the side.
@end deffn

@deffn Form @code{player} [id] properties@dots{}
This form defines players.
If the @var{id} is supplied and matches an existing player id,
then the player object is updated using the @var{properties},
otherwise a new player object will be created, using the given @var{id}
if supplied.
@end deffn

@deffn GlobalVariable @code{player-sides-locked} t/f
This variable is @code{true} when the player/side assignment may not
be changed while the game is starting up.
Defaults to @code{false}.
@end deffn

The number of players must always be less than the number of sides
(sides without players just don't do anything).

@deffn PlayerProperty @code{name} str
This property identifies the player by name.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{config-name} str
This property identifies a particular set of doctrine and other definitions
that the player is using.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{display-name} str
This property identifies the display being used by the player's interface.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{ai-type-name} str
This property is the type of AI that will play the side if requested or necessary.
The set of choices depends on what has been compiled into @i{Xconq}.
(The general-purpose AI type @code{"mplayer"} will usually be available,
but is not guaranteed.)
An @code{ai-type-name} of @code{""} means that no AI will run this player.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{password} str
This property is the encoding of a password that must be entered before this
player object can be reused successfully.
Defaults to @code{""}.
@end deffn

@deffn PlayerProperty @code{initial-advantage} n
This property is an initial relative strength at which the player should start.
Some synthesis methods can use this to give more units or some other
advantage to each player according to the requested strength.
Defaults to @code{1}.
@end deffn

@deffn GlobalVariable @code{advantage-min} n
@end deffn
@deffn GlobalVariable @code{advantage-max} n
@end deffn
@deffn GlobalVariable @code{advantage-default} n
These variables set the bounds and default values for players'
initial advantages.
An @code{advantage-max} of @code{0} means that there is no upper
bound on initial advantage (however, @i{Xconq} syntheses may not
be able to synthesize such a game).
Default to @code{1}, @code{0}, and @code{1}.
@end deffn

@subsection Rules of Side Configuration

The properties of a side can come from a number of different sources (here listed
in order of precedence):

@itemize

@item
Interface-specific sources (X resources, Mac preferences).

@item
Game-specific form in side config file (matched by module name).

@item
Generic form in side config file.

@item
The @code{side} form for the side.

@item
The @code{side-defaults} form.

@item
General program defaults.
@end itemize

Note that interface-specific and general config files can never alter
certain properties of a side, and can only alter others if they are
not locked.

@section Units

The basic @code{unit} form creates or modifies a unit.

@deffn Form @code{unit} id [type] properties@dots{}
This form defines a unit.
If a numeric @var{id} is supplied and matches the id of an existing unit,
then that unit will be modified by @var{properties},
and the optional @var{type} will be interpreted as a new type for the unit.
Otherwise a new unit will be created,
with either @var{id} as its id or
a arbitrarily-selected one if @var{id} is already in use.
If the unit's id is newly-generated and no type has been specified,
then type #0 (first-defined type) will be the type of the unit.
An id of @code{0} can never match an existing unit id, so effect
will be as if it had been omitted.
@end deffn

@deffn Form @var{unit-type-name} x y [side-id] properties@dots{}
This is an abbreviated form, in which
the x,y position is required, and an optional side id may be included.
The @var{unit-type-name} may be any valid unit type name or
defined name.
@end deffn

Since there may be many units whose properties are similar, there
is a ``default unit'' whose properties fill in missing properties in
individual unit declarations.

@deffn Form @code{unit-defaults} reset properties@dots{}
This form sets the default values for all subsequent units read in,
in this and every other module not yet loaded.
The set of defaults is additive,
so for instance you can repeatedly change the default side of units.
If the optional symbol @code{reset} has been supplied for @var{reset},
then all the defaults will be changed to the basic default
values, as described in this manual.
@end deffn

@deffn Symbol @code{reset}
@end deffn

@subsection Unit Properties

This section lists properties of individual units.
In general, they default to the most common or reasonable values,
so need not always be specified, even in a saved game.

@deffn UnitProperty @code{@@} x y [z]
This property is the position of the unit.
Defaults to @code{-1,-1,0}, which causes the unit to be placed randomly.
The optional altitude @var{z} can also be set separately with
the property @code{z} below.
If @i{z} is even and the unit is in the open,
then the unit's altitude is @i{z/2};
if @i{z} is odd, then @i{(z-1)/2} is the type of connection terrain
that the unit is on.
@end deffn

@deffn UnitProperty @code{z} z
This property is identical to the optional z part of the @code{@@} property.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{s} side
This property is the side of the unit.
It can be either a side name/noun/adjective (string) or id (number).
A value of @code{0} or @code{"independent"}
means that the unit is independent.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{#} n
This property is the id of the unit.
Defaults to a game-selected value.
@end deffn

@deffn UnitProperty @code{n} str
This property is the name of the unit.
Defaults to @code{""}.
@end deffn

@deffn UnitProperty @code{nm} n
This property is the number of the unit,
which starts at @code{1} and goes up.
Defaults to @code{0}, which means that the unit is unnumbered.
@end deffn

@deffn UnitProperty @code{cp} n
This property is the current completeness of the unit.
If negative, indicates that the unit will appear at a time
and place specified by the @code{appear} x-property.
Defaults to the @code{cp-max} for the type.
@end deffn

@deffn UnitProperty @code{hp} n
This property is the current hit points of the unit.
Will be restricted to the range [0, hp-max].
An hp of 0 means that the unit is dead and will not appear in the game.
Defaults to @code{hp-max} for the unit's type.
@end deffn

@deffn UnitProperty @code{cxp} cxp
This property is the combat experience of the unit.
Defaults to @code{0}.
@end deffn

@deffn UnitProperty @code{m} mtype-value-list
This property is the amounts of supplies being carried by the unit.
Defaults to @code{0} for each material type.
@end deffn

@deffn UnitProperty @code{tp} utype-value-list
This property is the level of tooling to build each type of unit.
Defaults to @code{0} for each unit type.
@end deffn

@deffn UnitProperty @code{in} n
This property is the id of the unit's transport.
Defaults to @code{0}, meaning that unit is not in any transport.
@end deffn

@deffn UnitProperty @code{feelings} side-value-list@dots{}
This property is the unit's true feelings towards each side,
including its own side.
Defaults to @code{0} for each side.
@end deffn

@deffn UnitProperty @code{x} obj
This property is the optional extension properties of the unit.
Its value may be any object.
Defaults to @code{()}.
@end deffn

@deffn Symbol @code{appear}
This is the extension property that indicates when and where a unit will appear
in the game.
@end deffn

@subsection Unit Action State

@deffn UnitProperty @code{act} subprops
This property specifies the current action state of the unit.
@end deffn

@deffn UnitActionStateProperty @code{acp} n
This property is the number of action points left to the unit for this turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{acp0} n
This property is the initial number of action points for this turn,
computed at the beginning of the turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{aa} n
This property is the actual number of actions executed by the
unit so far in the current turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{am} n
This property is the actual number of moves (cell entries)
executed so far in the current turn.
Defaults to @code{0}.
@end deffn

@deffn UnitActionStateProperty @code{a} action
This property is the next action that the unit will perform.
@end deffn

Note that if any unit-defining form has an @code{act} property,
@i{Xconq} will start at an appropriate point in the middle of a turn,
giving all other units zero acp and mp,
rather than starting at the beginning of the turn
and computing acp and mp for all units.

@subsection Unit Plan

@deffn UnitProperty @code{plan} type [subtype] properties@dots{}
This property describes the unit's current plan.
@end deffn

@deffn PlanType @code{none}
A unit with this type of plan does nothing.
It is used when a side has no player.
[assume empty agenda, always asleep?]
@end deffn

@deffn PlanType @code{passive}
This plan type is for when the side is being run by a human
directly controlling all units.
@end deffn

@deffn PlanType @code{defensive}
@end deffn

@deffn PlanType @code{exploratory}
@end deffn

@deffn PlanType @code{offensive}
@end deffn

@deffn PlanType @code{random}
@end deffn

@deffn PlanProperty @code{goal}
This property is the main goal of a unit's plan.
@end deffn

The possible types of goals are these:

@deffn GoalType @code{won-game}
@end deffn

@deffn GoalType @code{lost-game}
@end deffn

@deffn GoalType @code{world-is-known}
@end deffn

@deffn GoalType @code{vicinity-is-known}
@end deffn

@deffn GoalType @code{positions-known}
@end deffn

@deffn GoalType @code{cell-is-occupied}
@end deffn

@deffn GoalType @code{vicinity-is-held}
@end deffn

@deffn GoalType @code{has-unit-type}
@end deffn

@deffn GoalType @code{has-unit-type-near}
@end deffn

@deffn GoalType @code{has-material-type}
@end deffn

[also support some kind of hook for specific AIs?]

@deffn PlanProperty @code{tasks} tasks@dots{}
This property is the complete task agenda for the unit's plan.
It is a list of tasks.
Defaults to @code{()}.
@end deffn

@deffn TaskType @code{approach}
@end deffn

@deffn TaskType @code{ask-side}
@end deffn

@deffn TaskType @code{build} u n n2 unit-id
@end deffn

@deffn TaskType @code{capture} unit-id
@end deffn

@deffn TaskType @code{do-action} action
@end deffn

@deffn TaskType @code{hit-position} x y z
@end deffn

@deffn TaskType @code{hit-unit} unit-id
@end deffn

@deffn TaskType @code{move-dir} dir
@end deffn

@deffn TaskType @code{move-to} x y z dist
@end deffn

@deffn TaskType @code{occupy} unit
@end deffn

@deffn TaskType @code{pickup} unit
@end deffn

@deffn TaskType @code{repair} unit
@end deffn

@deffn TaskType @code{resupply}
@end deffn

@deffn TaskType @code{sentry} n
@end deffn

@deffn PlanProperty @code{asleep}
This property is true if the unit is asleep.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{reserve}
This property is true if the unit is in reserve.
Defaults to @code{false}.
@end deffn

@deffn PlanProperty @code{wait}
This property is true if the unit is waiting for orders.
Defaults to @code{false}.
@end deffn

@section Agreements

@deffn Form @code{agreement} [name/id] properties@dots{}
This form defines an agreement among a set of sides.
The name/id is a unique internal identifier.
@end deffn

@deffn AgreementProperty @code{type-name} str
This property is the name of the general type of agreement,
such a trade.
Defaults to @code{""}.
@end deffn

@deffn AgreementProperty @code{title} str
This property is the player-visible name of the agreement.
Defaults to @code{""}.
@end deffn

@deffn AgreementProperty @code{terms} forms@dots{}
This property is the list of terms of the agreement.
Defaults to @code{()}.
@end deffn

@deffn AgreementProperty @code{proposer} side
This property is the side that initially proposed the agreement.
@end deffn

@deffn AgreementProperty @code{signers} sides-list
Before the agreement is made,
this property is the proposed list of participants.
After the agreeement is made,
this is the actual list of participants.
@end deffn

@deffn AgreementProperty @code{willing-to-sign} side-list
This property is all the sides that have already agreed to this agreement,
on condition that all the other sides accept it.
@end deffn

@deffn AgreementProperty @code{known-to} side-list
@end deffn

@deffn AgreementProperty @code{enforcement} form
@end deffn

[include values such as @code{enforced??} and @code{publicity??}]

@deffn AgreementProperty @code{active} t/f
This property is @code{true} if the agreement is actually in effect.
Defaults to @code{true}.
@end deffn

@node Scorekeepers, History Design, Unit Design, Game Design

@section Scorekeepers

Scorekeepers are the objects that manage scoring, winning, and losing.
A game design need not define any scorekeepers,
and none are created by default.
A scorekeeper may either maintain a numeric score that is used at
the end of the game to decide rankings, or simply declare a side
to have won or lost.

@deffn Form @code{scorekeeper} name properties@dots{}
This form creates or modifies a scorekeeper with the given @var{name},
with the given @var{properties}.
@end deffn

@deffn ScorekeeperProperty @code{title} str
This property is a string that identifies the scorekeeper to the players.
Defaults to @code{""}.
@end deffn

@deffn ScorekeeperProperty @code{when} (type [exp])
This property is when the scorekeeper will be checked or updated.
Defaults to @code{after-turn}.
@end deffn

@deffn SKSym @code{before-turn} exp
This symbol indicates that the scorekeeper will run at the start of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn

@deffn SKSym @code{after-turn} exp
This symbol indicates that the scorekeeper will run at the end of each turn
matching @var{exp}, or after every turn if @var{exp} is not given.
@end deffn

@deffn SKSym @code{after-event} exp
This symbol indicates that the scorekeeper will run after every event
matching @var{exp}, or after every event if @var{exp} is not given.
@end deffn

@deffn SKSym @code{after-action} exp
This symbol indicates that the scorekeeper will run at the end of each action
matching @var{exp}, or after every action if @var{exp} is not given.
@end deffn

@deffn ScorekeeperProperty @code{applies-to} side-list
This property is the set of sides or side classes
to which the scorekeeper applies.
Scorekeepers apply only to sides that are in the game.
Defaults to @code{side*}.
@end deffn

@deffn ScorekeeperProperty @code{known-to} side-list
This property is the list of sides that know about this scorekeeper,
and can see the value of the score for each side that it applies to.
Defaults to @code{side*}.
@end deffn

@deffn ScorekeeperProperty @code{trigger} form
This property is an expression that is true when it is time
to start checking the scorekeeper's main test.
Once a scorekeeper is triggered, it remains active.
Defaults to @code{false}.
@end deffn

@deffn ScorekeeperProperty @code{triggered} t/f
This property is true if the scorekeeper is currently triggered.
Defaults to @code{true}.
@end deffn

@deffn ScorekeeperProperty @code{do} forms@dots{}
This property is a list of forms to execute in order
each time the scorekeeper runs.
Defaults to @code{()}.
@end deffn

@deffn ScorekeeperProperty @code{initial} value
This property is the value of the score upon game startup.
If this value is @code{-9999},
the scorekeeper does not maintain a numeric score.
Defaults to @code{-9999}.
@end deffn

@subsection Bodies

The forms in the body (the @code{do} property) of the scorekeeper
may be any of the forms listed here.

@deffn SKSym @code{last-side-wins}
If supplied as the only symbol in the body, then the scorekeeper
implements the usual ``last side left in the game wins'' behavior.
@end deffn

@deffn SKSym @code{if} test action
If the @i{test} evaluates to @code{true} or any nonzero number,
then the @i{action} will be done.
@end deffn

@deffn SKSym @code{cond} (test actions@dots{}) @dots{}
This is like Lisp's cond.
@end deffn

@deffn SKAct @code{stop} [message]
This stops the game immediately, with a draw for all sides.
@end deffn

@deffn SKAct @code{win} [sides] [own-message] [other-message]
@end deffn

@deffn SKAct @code{lose} [sides] [own-message] [other-message]
@end deffn

@deffn SKAct @code{end} [message]
This scorekeeper action ends the game immediately.
@end deffn

@deffn SKAct @code{add} exp [side]
This adds the result of evaluating @var{exp} to the score of the given side.
The value may be a negative number.
@end deffn

@subsection Functions

@deffn SKSym @code{and} exps
@end deffn

@deffn SKSym @code{or} exps
@end deffn

@deffn SKSym @code{not} exp
@end deffn

@deffn SKSym @code{=} exp1 exp2
@end deffn

@deffn SKSym @code{/=} exp1 exp2
@end deffn

@deffn SKSym @code{>} exp1 exp2
@end deffn

@deffn SKSym @code{>=} exp1 exp2
@end deffn

@deffn SKSym @code{<} exp1 exp2
@end deffn

@deffn SKSym @code{<=} exp1 exp2
@end deffn

@deffn SKSym @code{sum} types properties [test]
@end deffn

@subsection Scorefile

@deffn GlobalVariable @code{scorefile-name} str
@end deffn

@c [scorefile must include xconq version, module(s) plus versions,
@c player/side setup, dates/times, and list of scores/values plus
@c optional id as to which is which]

@node History Design, Battle States, Scorekeeper Design, Game Design

@section The History

All the important events in a game are logged into a history.

@deffn Form @code{evt} [date] type data
This form creates a single historical event.
If @i{date} is omitted, then the date will be the
same turn as for the last event read.
@end deffn

@deffn EventType @code{log-started}
@end deffn

@deffn EventType @code{game-started}
@end deffn

@deffn EventType @code{side-joined}
@end deffn

@deffn EventType @code{side-lost}
@end deffn

@deffn EventType @code{side-withdrew}
@end deffn

@deffn EventType @code{side-won}
@end deffn

@deffn EventType @code{unit-started-with}
@end deffn

@deffn EventType @code{unit-created}
@end deffn

@deffn EventType @code{unit-completed}
@end deffn

@deffn EventType @code{unit-acquired}
@end deffn

@deffn EventType @code{unit-captured}
@end deffn

@deffn EventType @code{unit-moved}
@end deffn

@deffn EventType @code{unit-assaulted}
@end deffn

@deffn EventType @code{unit-damaged}
@end deffn

@deffn EventType @code{unit-killed}
@end deffn

@deffn EventType @code{unit-vanished}
@end deffn

@deffn EventType @code{unit-wrecked}
@end deffn

@deffn EventType @code{unit-garrisoned}
@end deffn

@deffn EventType @code{unit-disbanded}
@end deffn

@deffn EventType @code{unit-starved}
@end deffn

@deffn EventType @code{unit-left-world}
@end deffn

@deffn EventType @code{game-ended}
@end deffn

@deffn EventType @code{log-ended}
@end deffn

@deffn EventType @code{action-ok}
@end deffn

@deffn EventType @code{action-error}
@end deffn

@deffn EventType @code{cannot-do}
@end deffn

@deffn EventType @code{insufficient-acp}
@end deffn

@deffn EventType @code{insufficient-material}
@end deffn

@deffn EventType @code{not-implemented-yet}
@end deffn

@deffn EventType @code{action-done}
@end deffn

@deffn EventType @code{move-error}
@end deffn

@c should flush this one
@deffn EventType @code{insufficient-mp}
@end deffn

@deffn EventType @code{cannot-leave-world}
@end deffn

@deffn EventType @code{destination-too-far}
@end deffn

@deffn EventType @code{destination-full}
@end deffn

@deffn EventType @code{overrun-failed}
@end deffn

@deffn EventType @code{overrun-failed}
@end deffn

@deffn EventType @code{fire-into-outside-world}
@end deffn

@deffn EventType @code{fire-into-too-far}
@end deffn

@deffn EventType @code{fire-at-too-far}
@end deffn

@deffn EventType @code{fire-into-too-near}
@end deffn

@deffn EventType @code{fire-at-too-near}
@end deffn

@deffn EventType @code{too-far}
@end deffn

@deffn EventType @code{too-near}
@end deffn

@node Battle States, , History Design, Game Design

@section Battle States

Battles always have exactly two ``sides'', referred to as A and B so
as not to confuse them with sides in the game.

@deffn Form @code{battle} a-list b-list@dots{}
@end deffn

Each list has the form
@example
((<unit> <commitment>) ...)
@end example

@section Types in General

Types are the foundation of @i{Xconq} game designs.
Nearly all the rules and game parameters are associated
with the unit, material, and terrain types.
There is no sort of type hierarchy; instead, most forms allow sets of types
to be used in the place of single types.

Each type has an index associated with it, starting from 0.
This index never appears directly, and cannot be set.
This does mean that types have an order, so the order in which
types are defined is sometimes significant.
These cases will be noted.
The order is always the order in which the types appear in the file,
so it is always the same.

@subsection Naming

The names of types need not be distinct from each other,
but you run the risk of player confusion if they share names.

@deffn TypeProperty @code{name} string
This property is the specific name of the type.
This name will be displayed to players; the exact format
is up to the interface, but will typically
depend on the name's length and the space available in the display.
If no type names have been defined, the internal type name (see below)
will be used.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{long-name} string
This property is a fully spelled-out name for the type.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{short-name} string
This property is an abbreviated name of r
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{generic-name} string
This property is like @code{name}, but identifies the type less specifically,
and several types may have the same generic name.
If no generic names are defined, then the regular type names will be used.
This is useful when making abbreviated lists, so that related types
get counted together.
Defaults to @code{()}.
@end deffn

As an example of the distinction between type names and generic type name,
the names of a automobile type might be @code{"1965 Mustang"},
@code{"Mustang"}, and @code{"M"},
while the generic name is @code{"auto"}.
Then the interface could choose to display a parking lot as containing
either @code{"4 auto"} or @code{"2 Mustang 1 Edsel 1 Jeep"}.

Note that names specified as properties are strings only, and are
not defined as evaluable symbols.

@subsection Imaging

The interpretation of these properties is entirely up to each interface;
see the appropriate interface documentation for details.

@deffn TypeProperty @code{image-name} str
This property is the name of the type's image.
If undefined or unusable for some reason,
the interface will display the type in some default manner, such as
a solid-color square or a string.
@end deffn

For example, in X11,
the name might be the name of a file in the usual bitmap format, as
produced by the @var{bitmap} program.  The actual file name is produced
by appending @code{".b"}.
(The situation in X is actually more complicated than this.)
See the interface documentation for details on how the interface
uses the image.

@deffn TypeProperty @code{color} str
This property is the name of the preferred color for this type.
Both normal color names and the strings @code{"bg"} and @code{"fg"}
(meaning ``foreground color'' and ``background color'')
may be used.
If the image is in color, then this property has no effect.
Defaults to @code{"fg"}.
@end deffn

@deffn TypeProperty @code{char} str
This property supplies a single character for this type
(all characters after the first one in @var{str} are ignored).
Defaults to @code{""}.
@end deffn

@subsection Documentation

@deffn TypeProperty @code{description} list@dots{}
This property is a list of lists describing different ways in which
an instance or instances of this type may be described textually.
This information may be used in narrative descriptions and by some
interfaces.
[describe syntax of the lists - are similar to name grammars]
If @code{()}, then the instance will be described in some default
fashion, such as (for units) @code{"the <side> <ordinal> <type>"}.
Defaults to @code{()}.
@end deffn

@deffn TypeProperty @code{help} string
This property is a brief (preferably one-line) description of the type.
Defaults to @code{""}.
@end deffn

@deffn TypeProperty @code{notes} strings@dots{}
This property is detailed documentation about the type.
The formatting of the strings is up to the interface,
but in general each string is a separate line,
and the string @code{""} indicates a paragraph break.
Defaults to @code{()}.
@end deffn

@subsection Availability

It may be that a set of types is larger than strictly necessary for
a particular game.  You can make any type unavailable, which means
that irrespective of any other controls, that type cannot come into
play during a game.  You can also make it available only for particular
turns.

@deffn TypeProperty @code{available} n
If the value of this property is greater than 0, then this type is available
in the game on or after turn @var{n}.
If the value is less than 0, then the type is available,
but only until turn @var{-n}.
If the value is 0, then the type is never available.
Defaults to @code{1}, which means that the type is always available.
@end deffn

If a type becomes unavailable and there are units of that type in play,
then they will vanish immediately.

@subsection Type Extension

It may occasionally be necessary to add new kinds of
information to a type.
For instance, new synthesis methods may require special data,
or an interface may be able to use extra hints to improve its display.
The @code{extensions} property can be used to store this kind of data.

@deffn TypeProperty @code{extensions} properties@dots{}
This property is a catch-all for nonstandard type properties.
Anything may appear here, but it will only be interpreted as much as needed,
and unrecognized extensions will not be warned about (so if you misspell
one, you won't hear about it).
@end deffn

@node Unit Types, Command Chain, General, Type Definition

@section Unit Types

@deffn Form @code{unit-type} symbol properties@dots{}
This form defines a new type of unit.
The @var{symbol} is required and must be previously undefined.
The bindings in @var{properties} are then added to the type one by one.
If no other name properties are defined, the @var{symbol} may be displayed
to players (see above).
You can define no more than 126 types of units.
@end deffn

The @var{symbol} here becomes the unit type's ``internal type name''
which is guaranteed unique.
To make synonyms for the internal type name, use @code{define}.

@deffn GlobalVariable @code{u*}
This variable evaluates to a list of all unit types,
listed in the order that they were defined.
This list always reflects the list of types at the moment it is evaluated.
@end deffn

@deffn GlobalVariable @code{non-unit}
This variable [constant?] evaluates to a value that is NOT a unit type.
This is needed in several places to enable/disable features.
Use of this in any other way is an error,
and may or may not be detected before it causes a crash.
@end deffn

@subsection Unit Naming

@deffn UnitTypeProperty @code{namer} namer-id
This property is the namer that will be used to generate names for units,
if the unit's side does not have a namer, or the unit is
independent and not in any country.
Defaults to @code{0}, which leaves the unit unnamed.
@end deffn

@deffn UnitTypeProperty @code{assign-number} t/f
This property is true if the unit should have a serial number assigned to it
by the side it belongs to.
Serial numbers are maintained for each type on each side separately.
Defaults to @code{true}.
@end deffn

@subsection Class-Restricted Unit Types

Sometimes the designer will want to make different sides have different types
of units.  Although this can be done by setting up scenarios appropriately,
that won't close all the loopholes that might allow a side to get units that
should only ever belong to another side.

The first step is to define a class for each side.  For instance,
a side named @code{"Rome"} might have a class @code{"Roman"},
while the sides named @code{"Aedui"} and @code{"Parisii"}
could both be in the class @code{"barbarian"}.

@deffn UnitTypeProperty @code{possible-sides} exp
This property restricts the unit type to only be usable
by a side meeting the conditions of @var{exp}.
If @var{exp} is a string, it restricts the unit type to only
be usable by a side whose class includes a matching string.
This can also be a boolean combination.
Independent units belong to a side whose class is @code{"independent"}.
The default of @code{""} allows the unit to belong to any side.
@end deffn

@subsection Self-Units

The self-unit can be any type, including one that cannot act;
for instance, a capital city could be the self-unit, thus making
its defense all-important for a player.

@deffn GlobalVariable @code{self-required} t/f
This variable is true if each side is required to have a self-unit at all times.
Defaults to @code{false}.
[this should also have a related side property]
@end deffn

@deffn UnitTypeProperty @code{can-be-self} t/f
This property says that the type of unit can represent the side directly.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-changeable} t/f
This property is true if the player can choose to change a self-unit of
this type at any time.
Otherwise the self-unit can be changed only if the current one dies.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{self-resurrects} t/f
This property is true if when the self-unit dies, another unit of an allowable type
becomes the self-unit automatically.
Defaults to @code{false}.
@end deffn

Observe that these parameters can be used to develop various forms of
backup, so that a player can start out as a capital city, resurrect as
a town, change self to one of several towns, then lose when all the towns
are lost.

@deffn Table @code{control-chance-at} u1 u2 -> n%
@end deffn

@deffn Table @code{control-chance-adjacent} u1 u2 -> n%
@end deffn

@deffn Table @code{control-chance} u1 u2 -> n%
@end deffn

@deffn Table @code{control-distance-max} u1 u2 -> dist
This table gives the maximum distance from self-unit @var{u1}
at which units of type @var{u2}
can be controlled directly.  Units further away always act on their own
(as if the doctrine said so[?]).
If this value is < 0, then @var{u1} can never directly control
any other @var{u2} on the side.
Defaults to @code{infinity}.
@end deffn

@subsection Limiting Unit Quantities

The effect of these is
to prevent any extra units from being created or from going over to a
side, regardless of the reason.
This happens by either preventing player actions that would
result in exceeding a limit (such as when building units), or by making
the unit vanish instantly (such as when capturing a unit).

@deffn GlobalVariable @code{units-in-game-max} n
This variable is the maximum number of all types of units, on all sides,
including independents, that may exist at any time, including initially.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn GlobalVariable @code{units-per-side-max} n
This variable is the maximum number of units (of all types together)
that any side may have, at any time.  Events that would cause
the limit to be exceeded, such as capturing a unit, result in
either the unit vanishing or becoming independent.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

There is no limit on the number of units that may be independent.

@deffn UnitTypeProperty @code{type-in-game-max} n
This property is the maximum total of the given type, for all sides together.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@deffn UnitTypeProperty @code{type-per-side-max} n
This property is the maximum number of units of the given type allowed to each side.
Defaults to @code{-1}, which means that there is no limit.
@end deffn

@subsection Hit Points

A unit's hit points determine how healthy it is.
If a unit's hp goes below 1, it is either @dfn{wrecked},
meaning that it changes to a new type
@code{wrecked-type} or else it @dfn{vanishes},
meaning that it is completely cleared from the world.

@deffn UnitTypeProperty @code{hp-max} n
This property is the maximum number of hit points for (each part of) a unit.
Completed units start with this many hit points.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{parts-max} n
This property declares that a unit is to be treated
as an aggregate of @var{n} smaller identical units.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{wrecked-type} unit-type
This property is the type of unit that a unit with 0 hp will become.
For instance, a destroyed ``fort'' might become a ``rubble pile'' unit.
If its value is @code{non-unit}, then the destroyed unit just vanishes.
The @code{wrecked-type} of a type must be a different type.
Defaults to @code{non-unit}.
@end deffn

The transformation to the wrecked type does not change position or name.
The transformed unit has full hp, supplies are conserved as much as possible,
tooling is preserved, and any unit plan is erased.
It has the same number of parts, or as many as possible if that is fewer.
It may be that the
wrecked type is on terrain that it cannot survive on; in that case, it
will be wrecked again, repeating until the unit either vanishes
or is in a viable position, or this process has been repeated
more times than the number of unit types (prevents infinite loops).
Any excess occupants will be removed and either placed in another nearby
unit or in the open, or will vanish if there is no other option.

@deffn UnitTypeProperty @code{hp-recovery} n
This property is the number of 1/100 hp recovered per turn.
Recovery happens automatically, as opposed to repair,
which requires explicit action.
The amount @i{n} / 100 is recovered automatically each turn,
while @i{n} mod 100 is the percent chance of recovering 1 hit point
in addition.
Defaults to @code{0}.
@end deffn

@subsection Experience

@deffn UnitTypeProperty @code{cxp-max} cxp
This property is the maximum combat experience this type of unit can have.
Defaults to @code{0}.
@end deffn

@subsection Tech Levels

Before it can do anything with a type of unit,
the side must have the appropriate tech level for that type,
which is just a number ranging from 0 up to @code{tech-level-max}.
Each type has a distinct tech level.

Tech levels always increase
(since they represent abstract knowledge rather than physical plant).
Tech can be transferred freely to any other side
via the message @code{tech} [xref to messages].

For each unit type, the following parameters define the minimum tech levels at
which sides can do various things.

@deffn UnitTypeProperty @code{tech-to-see} tl
This property is the minimum tech level that a side must have before it can see
a unit of this type.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-use} tl
This property is the minimum tech level that a side must have in order to use
this type of unit.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-dissect} tl
This property is the minimum tech level
that a side must have in order to dissect
this type of unit and thereby increase its tech level.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-from-dissection} tl
This property is the tech level that may be reached
by acquiring a unit of this type.
Since this is expressed as a minimum,
repeated acquisitions have no additional effect.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-to-build} tl
This property is the minimum tech level that a side
must have in order to build this type of unit.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-max} tl
This property is the absolute maximum tech level possible for this type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tech-crossover} u1 u2 -> n%
This table is the minimum tech level for @var{u2} that is guaranteed by a particular
tech level for @var{u1}, expressed as a percentage of the @code{tech-max}
for the types.
For instance, if @code{tech-crossover} is 80, and the tech level for @var{u1}
is 10 out of a max of 20, and the max for @var{u2} is also 20,
then the side has a tech for @var{u2} at least 8.
Defaults to @code{0}.
@end deffn

It is possible to gain some tech level just by being in the same game
with a side that is more advanced.

@deffn UnitTypeProperty @code{tech-leakage} .01tl
This property is the amount of tech level gain per turn that can happen
to any side's tech level that is less than the max of all sides in the game.
This only happens if at least one unit on the side has nonzero coverage
of a unit on a more advanced side.
Defaults to @code{0}.
@end deffn

@subsection Feelings and Attitudes

@deffn UnitTypeProperty @code{attitudes-max} n
This property is the number of different sides that a unit can
have feelings about.
Defaults to @code{0}.
@end deffn

@subsection Chain of Command

Some types of units can give orders to other units.

@deffn Table @code{can-command} u1 u2 -> t/f
@end deffn

[how does this work with control model?]

@subsection Point Value

Point values provide an abstract way to characterize the overall importance
of a unit type.
Point values figure into some scorekeepers, and are used by AIs.

@deffn UnitTypeProperty @code{point-value} n
This property is the ``value'' of a unit.
Defaults to @code{1}.
@end deffn

@node Terrain Types, Material Types, Point Value, Type Definition

@section Terrain Types

Terrain types are associated with the cells, borders,
connections, and coatings in a world.

@deffn Form @code{terrain-type} name properties@dots{}
This form defines a new type of terrain, named by @var{name}.
Details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{t*}
This variable evaluates to a list of all terrain types,
listed in the order that they were defined.
@end deffn

@deffn GlobalVariable @code{non-terrain}
This variable has a value that is guaranteed not to be a terrain type.
@end deffn

@subsection Terrain Subtypes

Terrain can appear in four different roles: as the interior of
a cell, as a border between cells, as a connection between cells,
or as a coating overlaying the normal terrain.
The terrain subtype says which role a type can play.

@deffn TerrainTypeProperty @code{subtype} subtype
This property is the role that the terrain type can appear in.
Defaults to @code{cell}.
@end deffn

@deffn GlobalConstant @code{cell}
This constant indicates that terrain can fill a cell.
All units in the open and with an altitude of 0 are assumed
to be surrounded by the cell terrain.
@end deffn

@deffn GlobalConstant @code{border}
This constant indicates that the terrain can be a border.
@end deffn

@deffn GlobalConstant @code{connection}
This constant indicates that the terrain can be a connection.
@end deffn

@deffn GlobalConstant @code{coating}
This constant indicates that the terrain can be a coating.
A @dfn{coating} is a temporary terrain modification.
The classic example is snow,
which effectively changes some kinds of terrain,
but not completely and usually not permanently.
Cells can have varying heaviness of each type of coating.
@end deffn

@deffn Table @code{coating-depth-min} t1 t2 -> n
In order for a coating @var{t1} to ``stick'',
this table says much must be added all at once to terrain @var{t2}.
A coating depth that drops below this will disappear immediately.
Defaults to @code{0}.
@end deffn

@deffn Table @code{coating-depth-max} t1 t2 -> n
This table is the upper limit on coating depth.
Defaults to @code{0}.
@end deffn

Terrain types may have additional subtype attributes that
are used only during synthesis, to select appropriate subtypes
for special purposes.

@deffn TerrainTypeProperty @code{subtype-x} n
This property is extra subtype information, used in synthesis.
Defaults to @code{no-x}.
@end deffn

@deffn GlobalConstant @code{river-x}
This constant indicates that synthesis methods should treat this
type as a river.
The terrain type may be either a border or a connection.
@end deffn

@deffn GlobalConstant @code{valley-x}
This constant indicates that synthesis methods should treat this type
as a valley.
@end deffn

@deffn GlobalConstant @code{road-x}
This constant indicates that synthesis methods should treat this type
as a road.
@end deffn

@deffn TerrainTypeProperty @code{liquid} t/f
This property is true if the terrain type represents a liquid,
which means that
adjacent cells of liquid have the same elevation and so forth.
Defaults to @code{false}.
@end deffn

@subsection Terrain Compatibility

Terrain types are not always mutually compatible.

@deffn Table @code{adjacent-terrain-effect} t1 t2 -> t3
This table specifies what will happen to a cell of type @var{t1}
adjacent to a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
nothing will happen, otherwise it will become a cell of type @var{t3}.
Defaults to @code{non-terrain}.

t1 == t3 means no effect.

This also specifies what will happen to a border of type @var{t1}
adjacent to a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
then the border cannot border the cell, otherwise it
will become a border of type @var{t3} (or disappear if
@var{t3} cannot be a border).
Defaults to @code{non-terrain} [a problem, will erase borders usually]

This also specifies what will happen to a connection of type @var{t1}
in a cell of type @var{t2}.  If @var{t3} is @code{non-terrain},
then the connection cannot be in the cell, otherwise it
will become a connection of type @var{t3} (or disappear if
@var{t3} cannot be a connection).
Defaults to @code{non-terrain} [a problem, will erase connections usually]
@end deffn

@subsection Other Terrain Properties

@deffn TerrainTypeProperty @code{elevation-min} dist
@end deffn
@deffn TerrainTypeProperty @code{elevation-max} dist
These properties define the minimum and maximum possible values
for the elevation in a cell of given terrain type.
Both default to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-min} n
@end deffn
@deffn TerrainTypeProperty @code{temperature-max} n
These properties define the minimum and maximum possible values
for the temperature in a cell of given terrain type.
They default to @code{-50} and @code{50}.
@end deffn

@deffn TerrainTypeProperty @code{wind-force-min} n
@end deffn
@deffn TerrainTypeProperty @code{wind-force-max} n
@end deffn

@deffn TerrainTypeProperty @code{clouds-min} n
@end deffn
@deffn TerrainTypeProperty @code{clouds-max} n
@end deffn

@node Material Types, Type Relationships, Terrain Types, Type Definition

@section Material Types

Materials are materials that are manipulated in mass quantities.
In general, material types just index arrays of unit supplies.

Lots of different material types can be thoroughly confusing.
You should use as few as possible.
The maximum number of material types is 126.

@deffn Form @code{material-type} symbol properties@dots{}
This form defines a new type of material, named by @var{symbol}.
Details are similar to those for unit types.
@end deffn

@deffn GlobalVariable @code{m*}
This variable evaluates to a list of all material types,
listed in the same order as they were defined.
@end deffn

@deffn GlobalVariable @code{non-material}
This variable has a value that is never a material type.
@end deffn

@subsection People

A material type can be designated as representing people.

@deffn MaterialTypeProperty @code{people} n
This property is the actual number of individuals
represented by 1 of a material.
If 0, then the material type does not have people associated with it at all.
Defaults to @code{0}.
@end deffn

Multiple types of materials can represent different types of people,
so for example you could have one type @code{nomad} with 10 people/material,
and another type @code{urbanite} with 10,000 people/material.

The basic cell capacities for materials also constrains people
materials, also there is a limit on the number of individuals.

@deffn TerrainTypeProperty @code{people-max} n
This property is the maximum number of individuals allowed
in a cell of this type of terrain.
This is checked at the end of each turn;
any excess will be moved into adjacent cells or disappear entirely.
Defaults to @code{-1}, which allows any number of people in a cell.
@end deffn

@node Type Relationships, Hints, Material Types, Type Definition

@section Static Relationships Between Types

In general, static relationships are those that must always hold
during a turn.  @i{Xconq} will usually only test these when
necessary, but the code is free to do so more often.

@subsection Occupants and Transports

A unit inside another unit is an ``occupant'' in a ``transport'',
even if the ``transport'' can never move.
There are two kinds of capacity.  Generic capacity is shared by
all different types, while guaranteed capacity is for a particular
type only.

@deffn UnitTypeProperty @code{capacity} n
This property is the limit on the sum of sizes of units that may occupy this
type of unit, not counting the exclusive capacities.
Defaults to @code{0}.
@end deffn

@deffn Table @code{unit-size-as-occupant} u1 u2 -> n
This table is the ``size'' of a (full-sized) unit @var{u1} when it is in
a transport @var{u2}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{unit-capacity-x} u1 u2 -> n
This table is the number of units of type @var{u2} that are guaranteed
a place in a unit of type @var{u1}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-max} u1 u2 -> n
This table is the upper limit on the number of occupants of this type
(not counting @code{unit-capacity-x}).
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{occupant-total-max} n
This property is the upper limit on occupants of all types together.
Defaults to @code{-1}, which allows unlimited occupancy.
@end deffn

A unit that is an occupant may not always have the same capabilities
as when it is out in the open.

@deffn Table @code{occupant-vision} u1 u2 -> n%
This table is the quality of @var{u1}'s vision while an occupant of @var{u2},
expressed as a percentage of normal coverage.
Defaults to @code{100}.
@end deffn

@deffn Table @code{occupant-combat} u1 u2 -> n%
This table is @code{true} if @var{u1} do any combat action
while an occupant of @var{u2}.
Defaults to @code{100}.
@end deffn

@deffn Table @code{occupant-can-construct} u1 u2 -> t/f
This table is @code{true} if @var{u1} can build things while an occupant of @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-can-have-occupants} u1 u2 -> t/f
This table is @code{true} if @var{u1} can have occupants of its own
while an occupant of @var{u2}.
Defaults to @code{false}.
@end deffn

@subsection Units and Terrain

@deffn Table @code{vanishes-on} u t -> t/f
This table is @code{true} if a unit @var{u} will disappear instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn

@deffn Table @code{wrecks-on} u t -> t/f
This table is @code{true} if a unit @var{u} will wreck instantly if it
somehow ends up on terrain of type @var{t}.
Defaults to @code{false}.
@end deffn

@deffn TerrainTypeProperty @code{capacity} n
This property is the limit on the sum of unit sizes that may share this cell.
Defaults to @code{1}.
@end deffn

@deffn Table @code{unit-size-in-terrain} u t -> n
This table is the ``size'' of a (full-sized) unit @var{u} when it is
in/on the terrain @var{t}.
Defaults to @code{1}.
@end deffn

@deffn Table @code{terrain-capacity-x} u t -> n
This table is the number of (full-sized) units of type @var{u}
that are guaranteed to have a place in the cell.
Defaults to @code{0}.
@end deffn

Note that the units' sides are irrelevant;
the sizes of units of all sides are added together.
Limits are calculated separately for the connection and open terrain
in a cell, but some unit types negate the capacity of connections.

@deffn Table @code{capacity-negation} u t -> t/f
This table is @code{true} if when @var{u} is in the open in a cell
that includes connections of type @var{t},
those connections have no capacity for units.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{stack-order} n
This property is the relative position of this type of unit within a stack of
different units.
Larger values put units higher in the stack.
The exact values are unimportant, they are just used as sort keys.
The use of this value is to ensure that particular types are ``seen first''
when looking at a cell, so for instance if a truck and a city are stacked
on the same cell, everybody will see the city and not the truck.
The owner of these units can still see them.
If the stack-order of two units is the same,
then the higher-numbered type will be higher in the stack.
Defaults to @code{0}.
@end deffn

There is a possible bizarrity with stacking limits and units that can't
see each other when in the same hex, namely that a player could be prevented
from moving a unit into a cell that looks like it has enough room.

@subsection Units and Materials

Units can carry materials.  As with occupants, there is
both a generic storage space and spaces specialized for
each material type.

@deffn UnitTypeProperty @code{storage} n
This property is a unit's generic space for materials of any type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-size-in-unit} u m -> n
This table is the amount by which the given material counts against
the unit's storage space.
Defaults to @code{1}.
@end deffn

@deffn Table @code{unit-storage-x} u m -> n
This table is the space reserved specifically for each
type of material.
Defaults to @code{0}.
@end deffn

Materials that represent people can damage units and/or
surrender to them.

@deffn Table @code{people-sabotage-rate??} u m -> .01hp
This table is the attrition rate of a unit in the open in
a cell with people on a hostile [define] side.
@end deffn

@deffn Table @code{people-surrender-chance} u m -> n%
This table is the chance that people of type @var{m} will change sides
if a unit of type @var{u} is in their cell.
Defaults to @code{0}.
@end deffn

@subsection Terrain and Materials

@deffn Table @code{terrain-storage-x} t m -> n
This table is the amount of a material @var{m} that can be accumulated in a cell
with terrain @var{t}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-size-in-terrain} t m -> n
@end deffn

@section Vision

Each unit can have two kinds of vision; @dfn{generic vision}
or just @dfn{vision} that
represents an aggregate of actual vision, circumstantial evidence,
and whatever else, and @dfn{specialized vision} that works similarly,
but can be given different characteristics.
Also, units can spy on each other.

Both generic and specialized vision generate a ``coverage'' for
each cell.  Coverage of zero means nobody is observing the cell,
and it may go arbitrarily high.
When a unit is sufficiently well-covered and has been seen,
then it is ``under observation'', which means that view data
will always be current.

@deffn GlobalVariable @code{see-all} t/f
This variable is @code{true} if everything in the world, units, terrain, etc,
is always visible at all times, including initially.
It takes precedence over @i{all} other visibility and spying parameters.
Defaults to @code{false}.
@end deffn

@deffn GlobalVariable @code{see-terrain-always} t/f
If this variable is @code{true}, then any side that has seen the terrain of a cell
will be informed if that terrain ever changes.
Defaults to @code{true}.
@end deffn

@deffn GlobalVariable @code{see-weather-always} t/f
@end deffn

@deffn UnitTypeProperty @code{see-always} t/f
This property is @code{true} when a unit is always visible
after it has been seen once,
so that side changes, movements, etc will be seen forever afterwards.
If the unit moves into terrain that has not been seen,
then that terrain also becomes seen as well.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{see-occupants} t/f
This property is @code{true} when a unit's occupants are also seen
whenever the unit itself is under observation.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{see-action} t/f
If this property is @code{true},
then the unit's chance to be seen by other sides will be
tested each time the unit acts in any way.
This property is in addition to the check at the beginning of each turn.
Defaults to @code{true}.
@end deffn

@deffn UnitTypeProperty @code{see-movement} t/f
If this property is @code{true},
then the unit's chance to be seen by other sides will be
tested each time the unit moves.
@code{see-action} implies @code{see-movement}.
Defaults to @code{true}.
@end deffn

@deffn UnitTypeProperty @code{see-combat} t/f
@end deffn

The people in a cell effectively view (for their side)
all units in that cell.
Some units can hide from the people.

@deffn Table @code{visibility-to-people} u m -> n%
This table is the chance that the people of the
given type @var{m} will see a unit of type @var{u}.
This will be evaluated for each people type individually,
once at the beginning of each turn, and once for each populated cell
that the unit enters during the turn.
Defaults to @code{100}.
@end deffn

@deffn TerrainTypeProperty @code{thickness} dist
This property is the thickness of the terrain, which is the difference between
the ``ground'' of the terrain and its top.
(See vision parameters for the effects of terrain thickness.)
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{weather-vision-range} dist
[should be a table so can't see a long ways off from within forest?]
@end deffn

@subsection Generic Vision

@deffn UnitTypeProperty @code{vision-range} dist
This property is the maximum range of vision coverage by the unit.
A value of @code{-1} disables all vision,
@code{0} means only units in the same cell may be seen,
and @code{1} means units in adjacent cells may be seen.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{vision-bend} n
This property is the amount by which a unit can see ``around corners''.
0 means that vision is strictly line-of-sight,
while 100 means that elevations never obstruct vision.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{vision-at} n
@end deffn
@deffn UnitTypeProperty @code{vision-adjacent} n
@end deffn
@deffn UnitTypeProperty @code{vision-at-max-range} n
Each of these properties represents the amount of vision coverage provided
by the unit type at various ranges.
All default to @code{1}.
@end deffn

@deffn Table @code{visibility} u t -> n%
This table is the basic chance to see a unit of type @var{u} when
in terrain of type @var{t},
expressed as a percentage of the coverage by the viewing side.
Defaults to @code{100}.
@end deffn

@deffn Table @code{combat-visibility} u1 u2 -> n%
This table is the basic chance to see a unit of type @var{u1} when
in combat with a unit of type @var{u2},
expressed as a percentage of the coverage by the viewing side.
This is evaluated for each combat action within a turn.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{lockon-chance} n%
This property is the chance that once seen, a unit will continue to be seen
while it is being covered.
This is effectively true for any unit
with a @code{visibility} of @code{100}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{eye-height} u t -> dist
This propety is the additional elevation above the unit's position that a unit
can see with, when in the given terrain.
Defaults to @code{0}.
@end deffn

@subsection Spying

A unit type can also be specified to do spying automatically.
The outcome of spying is calculated once/unit/turn,
at the beginning of the turn (after move calculation but before
any players can do anything).
Spying can happen to any unit not on the spying unit's side.

@deffn UnitTypeProperty @code{spy-chance} n.f%
This property is the chance that the unit's spies will find out something.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{spy-range} dist
This property is the maximum distance at which the unit's spies will find out
something.
Defaults to @code{0}.
@end deffn

@deffn Table @code{spy-quality} u1 u2 -> n%
This table gives the chance that @var{u1}'s spies will return information
about a unit of type @var{u2}.
Defaults to @code{100}.
@end deffn

@deffn Table @code{compromise-chance} u1 u2 -> n%
This table is the chance that if @var{u1}'s spies return information
about a unit of type @var{u2}, then that unit will always be
visible thereafter, as if it were @code{see-always}.
The compromised unit and its side will not be aware that
this has happened.
Defaults to @code{0}.
@end deffn

@section Game Initialization and Naming

Game initialization always starts by resetting all the game-defining data
structures to an empty state.  This means no types, no world, etc.
Then @i{Xconq} reads and interprets
all of the game modules that have been requested.
These modules may overwrite each other arbitrarily.
Then any command line or startup options
are processed (this may involve an interactive dialog),
and the random number generator is initialized.
and players are matched with sides
(any sides needed for players will be created and named at this time).
@i{Xconq} then executes a number of @i{synthesis methods}
to do various kinds of setup.

(Some interfaces might allow for confirmation of the setup before
launching into the game proper, but this cannot be assumed.)

Since the details of good game synthesis can be complicated,
synthesis methods are simply wired-in pieces of code.
Each method is self-contained; it assumes the game state to be valid,
it will determine its own applicability and
produce a valid result.  It will also acquire any data that it
needs, so does not require any special setup;  however, a method
may fail to run if it cannot find that data.
For instance, the usual fractal
terrain generator needs percentiles for each terrain type, and
will not function without them.  It may be that all the requested
synthesis methods fail; this is OK if @i{Xconq}'s data is present
and consistent, but otherwise @i{Xconq} will shut itself down, since
it has no remaining alternatives (think of this as a serious
programming error and fix the game design).

@deffn GlobalVariable @code{player-mix-default} form
@end deffn

@deffn GlobalVariable @code{player-mix-required} form
@end deffn

@section The Synthesis Method List

The synthesis method list specifies which methods will be run,
and in what order.
After they have all been run, @i{Xconq} runs a consistency and completeness
check.  For instance, there should be a world with terrain everywhere.
Failure at this point is fatal; @i{Xconq} will either exit
or return to a game setup dialog.

@deffn GlobalVariable @code{synthesis-methods} method-list
This variable is a list of synthesis methods.
If the list is empty, no synthesis methods will be run.
@end deffn

The list of synthesis methods is ordered, but should not contain duplicates
(it's conceivable that there is some reason to run a method twice, but
most won't do anything if they've already been executed once).

The default synthesis method list is
@example
(make-fractal-percentile-terrain
 make-countries
 make-independent-units
 make-roads
 make-rivers
 init-supplies
 name-geographical-features
)
@end example

The synthesis method list may also contain items of the form

@example
("program" forms...)
@end example

For each of these items, @i{Xconq} will attempt to find and run
an external program named @code{"program"},
giving it as input the result of evaluating the @code{forms},
and then reading the output of the program, which must be a valid
game module.  Any further details will depend on your system,
since each will use different conventions.
Note that this is NOT a portable construct; you cannot assume that
everybody will have built and installed the program you're using.

@subsection Fractal World

@deffn SynthesisMethod @code{make-fractal-percentile-terrain}
This method generates the terrain layer of a world.
It works by generating two distinct layers of random blobs,
known as the ``alt'' and ``wet'' layers,
then decides on a terrain type for each cell.
If elevations are defined,
then this method will use the alt layer to produce elevations. [how?]
@end deffn

@deffn GlobalVariable @code{alt-blob-density} n
@end deffn
@deffn GlobalVariable @code{wet-blob-density} n
These variables are the number of blobs to put down, at a rate of 1 per 10,000 cells.
Defaults to @code{500}.
@end deffn

@deffn GlobalVariable @code{alt-blob-size} n.f%
@end deffn
@deffn GlobalVariable @code{wet-blob-size} n.f%
These variables are the average number of cells in a blob,
expressed as hundredths of a percent of the number of cells in the world.
Defaults to @code{100}.
@end deffn

@deffn GlobalVariable @code{alt-blob-height} n
@end deffn
@deffn GlobalVariable @code{wet-blob-height} n
These variable are the amounts by which to increment or decrement within a blob.
Defaults to @code{1000}.
@end deffn

@deffn GlobalVariable @code{alt-smoothing} n
@end deffn
@deffn GlobalVariable @code{wet-smoothing} n
These variables specify the number of averaging steps
to perform after the blobs have been generated.
Defaults to @code{2}.
@end deffn

@deffn TerrainTypeProperty @code{alt-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{alt-percentile-max} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-min} n%
@end deffn
@deffn TerrainTypeProperty @code{wet-percentile-max} n%
These properties are
the percentiles of elevations and moistures that result in the given
terrain type.
Percentile ranges may overlap, in which case the earlier-defined
terrain type will be used.
If a cell has a alt and wet that does not fall in any of the ranges,
then terrain type 0 will be used there and players will be warned.
Mins defaults to @code{0}, maxes to @code{100}.
@end deffn

@subsection Maze World

@deffn SynthesisMethod @code{make-maze-terrain}
This method creates terrain that looks like a maze.
@end deffn

@deffn TerrainTypeProperty @code{maze-room-occurrence} n
This property is the weighted amount of this terrain type
in rooms in the maze.
@end deffn

@deffn TerrainTypeProperty @code{maze-passage-occurrence} n
This property is the weighted amount of this terrain type
in passageways in the maze.
@end deffn

@deffn GlobalVariable @code{maze-room-density} n
This variable is the fraction of the maze that is room.
@end deffn

@deffn GlobalVariable @code{maze-passage-density} n
This variable is the fraction of the area that is passageway.
@end deffn

@subsection Random World

The random world generator just assigns terrain and elevations randomly.

@deffn SynthesisMethod @code{make-random-terrain}
This method generates completely random terrain.
It uses a simple weighting to govern how much
of each terrain type appears, and makes random elevations as well.
@end deffn

@deffn TerrainTypeProperty @code{occurrence} n
This property is the percentage of the world that will be of this type.
Defaults to @code{1}.
@end deffn

@subsection Earthlike World

Earthlike generation uses algorithms that more closely approximate
realistic terrain.

@deffn SynthesisMethod @code{make-earthlike-terrain}
This method generates terrain that approximates what actually
appears on Earth.
@end deffn

@subsection River Generation

Rivers are borders or connections consisting of ``watery terrain''
that run downhill to regions of water.

@deffn SynthesisMethod @code{make-rivers}
This method looks for a border or connection
terrain type with a @code{subtype-x} of @code{river-x}.
then uses the world's elevation data to run rivers downhill
(always choosing the lowest of possible adjacent locations)
until they reach cell terrain with a @code{subtype} > 0.
This method will not run if there are no appropriate terrain types,
nor if there is no elevation data.
@end deffn

@deffn TerrainTypeProperty @code{river-chance} n%
This property is the chance that a river will start in or around a cell of this
terrain type.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{river-sink-terrain} t
If the value of this variable is a terrain type, then a cell completely
surrounded by river will be changed to be this type.
Defaults to @code{non-terrain}.
@end deffn

Note that the algorithm computes rivers in a deterministic way,
so high values of @code{river-chance} do not result in tangled rivers.

[does not use valley-x yet]

@subsection Road Generation

The road generation method makes networks of connection terrain between
particular unit types, usually those resembling cities.

@deffn SynthesisMethod @code{make-roads}
This methods synthesizes roads for an area.
For any connection type of terrain, if no layer has been created for it
already, and the type has a @code{subtype-x} of 3,
put down roads between any pair of units whose
@code{road-chance} is nonzero.
The method will attempt to share road routes whenever possible,
and choose terrain according to @code{road-into-chance}.
@end deffn

@deffn Table @code{road-chance} u1 u2 -> n%
This table is the chance that a road will be laid, running
from a unit of type @var{u1} to one of type @var{u2}.
This is not a symmmetrical relationship.
Defaults to @code{0}.
@end deffn

@deffn Table @code{road-into-chance} t1 t2 -> n%
This table is the chance that a road will be chosen to pass
from terrain of type @var{t1} into terrain of type @var{t2}.
Defaults to @code{100}.
@end deffn

@subsection Making Countries

The @code{make-countries} method is the usual way to set up a side's
starting units.

@deffn SynthesisMethod @code{make-countries}
This method works by looking for a likely place for the country,
randomly places a basic set of starting units within that area,
then expands the country outwards.
The parameters give you control over the mix of terrain types
in the country, as well as the size and relative positions of the
different countries.
This method runs on any side with fewer units than it is supposed
to start with, as given by the parameters below.
It places groups of units at locations separated from each other
by specified distances.
@end deffn

@deffn GlobalVariable @code{country-radius-min} dist
This variable is the radius of the country's initial area.
Defaults to @code{-1}, which allows the algorithm to calculate a ``reasonable''
country size appropriate to the given number of units.
@end deffn

@deffn GlobalVariable @code{country-separation-min} dist
@end deffn
@deffn GlobalVariable @code{country-separation-max} dist
These variables are the minimum and maximum
distances of country centers from each other, in cells.
If small, countries will mostly overlap;
if very large, then attempts to use small worlds will fail;
if the max and min are too close to each other, placements can also fail.
For both of these, a value of @code{-1} disables their effect.
Both default to @code{-1}.
@end deffn

The max separation bound needs to be satisfied for a country
with respect to only @i{one} other country,
so for instance the final layout may involve a long
``string'' of countries where the first and last countries are very far apart
from each other.
The minimum bound must be satisfied for all pairs of countries.

@deffn TerrainTypeProperty @code{country-terrain-min} n
This property is the minimum amount of terrain
that must be within the country's initial radius.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{country-terrain-max} n
This property is the most terrain of the given type that may appear.
If @code{-1}, then any amount may be present.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{start-with} n
@end deffn
@deffn UnitTypeProperty @code{independent-near-start} n
These properties set the number of units of the given type in a player's country.
These units are randomly scattered within the initial radius,
and the @code{favored} table (see below) decides which terrains
will be used.  Units may be placed inside each other; in fact,
units with no favored terrain will be made into occupants if possible.

The independent units will be placed after the ones belonging to the side,
so on the average they will get the less desirable locations in the country.
Both independent and the side's units will be named using the side's namers.
@end deffn

@deffn Table @code{favored-terrain} u t -> n%
This table sets
the probability of the unit type being on the given type of terrain at the
outset.  A value of @code{0} is an absolute prohibition against placing
the unit on that type of terrain, thus every game must specify at least
one non-zero value for some terrain type and some initial unit type.
Defaults to @code{100}.
@end deffn

Once the initial country area has been set up,
then you can allow the countries to expand outwards.
Expansion occurs at the same rate for all countries.
Countries may expand into and through each other.

@deffn TerrainTypeProperty @code{country-growth-chance} n%
This property is the chance that a country will expand onto an unclaimed cell
of the given terrain type.
Defaults to @code{100}.
@end deffn

@deffn TerrainTypeProperty @code{country-takeover-chance} n%
This property is the chance that a country will expand onto another country's cell
of the given terrain type.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{unit-growth-chance} n.f%
This property is the chance that a unit of the given type will be placed
when the country expands onto a cell.
The unit will only be placed if the @code{favored} chance is also true.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{independent-growth-chance} n.f%
This property is the chance that an independent unit of the given type will be placed
when the country expands onto a cell.
The @code{favored} chance is also evaluated.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{unit-takeover-chance} n.f%
This property is the chance that a unit of the given type in another country and
belonging to another side will be given to the growing side.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{independent-takeover-chance} n.f%
This property is the chance that an independent unit of the given type in
another country will be given to the growing side.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{country-radius-max} dist
This variable is a cap on the country growth process.
Values between @code{0} and @code{country-radius-min}
prevent country growth entirely,
while a value of @code{-1} allows growth to encompass the entire world.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{country-units-max} n
This property is a cap on the number of units given to the side's country.
Defaults to @code{-1}, which disables any limit.
@end deffn

@deffn GlobalVariable @code{growth-stop-chance} n%
This variable is the chance that a country's growth will stop,
if during the current [ring or round] no new cells were added
to the country.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{country-people-chance} n%
This property is the chance that the people's side will be changed to
match that for the country they are in.
@end deffn

@subsection Making Independent Units

For many games, it is useful to have independent units scattered randomly
across the world.  For instance, gold mines and treasure hoards would be
good for an exploration game, and independent castles for a medieval game.

@deffn SynthesisMethod @code{make-independent-units}
This method scatters independent units randomly
over the world.
This method will not run if the specified density of independent units
has already
been achieved, for instance from a predefined world or from country placement.
Independent units that should be inside other independents will be
handled correctly.
@end deffn

@deffn Table @code{independent-density} u t -> n
This table is the total number of independent units appearing throughout the world,
at the rate of @var{n} per 10,000 cells
of the given terrain type.
Any independent units already placed are counted first,
so this value represents final density.
If the sum of values for a given unit type is nonzero,
then at least one unit of that type will
be placed, even if the world is very small (i.e. the calculation of
numbers rounds up not down).
Defaults to @code{0}.
@end deffn

This method uses the @code{favored-terrain} table as the chance that a given
unit will be placed at a randomly-chosen position,
and it will keep trying different positions until a suitable one is
found.

@deffn TerrainTypeProperty @code{independent-people-chance} .01n%
This property is the chance that the people of a cell with this terrain type
will be made independent.
Deafults to @code{0}.
@end deffn

@subsection Initial Supply

By default, all units start out empty of materials.
The supply initialization method gives each unit a starting supply,
according to the stockpile tables.

@deffn SynthesisMethod @code{make-initial-materials}
This method fills unit and cell supplies to specified levels.
It runs only on units actually present at the moment it runs.
[what about scheduled reinforcements?]
@end deffn

@deffn Table @code{unit-initial-supply} u m -> n
This table is the amount of each material that each unit will start out with.
If the initial supply is greater than unit's capacity,
then the unit will just be filled to capacity.
Defaults to @code{0}.
@end deffn

@deffn Table @code{terrain-initial-supply} t m -> n
This table is the amount of material @var{m} that each cell
with terrain @var{t} will start out with.
Defaults to @code{0}.
@end deffn

@subsection Naming Geographical Features

Although named geographical features don't affect the outcome of a game
in any way, they are useful for ``color'' and for identifying locations
more readably.

@deffn SynthesisMethod @code{name-geographical-features}
This method identifies and names regions as geographical features,
such as mountain ranges and islands.
@end deffn

@deffn GlobalVariable @code{feature-namers} feature-namer-list
This variable is a list of feature types and their associated namers.
This is used for features not intersecting any country
with a namer for the feature's type.
@end deffn

@deffn GlobalVariable @code{feature-types} feature-expr-list
This variable is a list of feature types that may be identified.
[("lake" (group (sea shallows) 1))]
[("peak" (high-point 1 1%))]
@end deffn

@subsection Naming Units

@deffn SynthesisMethod @code{name-units-randomly}
This method gives names to previously-unnamed units,
using their usual [?] naming methods.
@end deffn

@subsection Making a Random Date

@deffn SynthesisMethod @code{make-random-date}
@end deffn

[how is this controlled?]

@section Setup Postprocessing

Some initialization steps will be done after all synthesis methods
have been run.

@subsection Initial View

By default, each side starts out knowing only what its units can
normally see at the beginning of the first turn.
These parameters alter that initial view.

@deffn GlobalVariable @code{terrain-seen} t/f
This variable is @code{true} if all the terrain of the world is known initially.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{initial-seen-radius} dist
This property specifies the radius of the area seen around each of
the starting units.
It computes visibility of terrain (cells and borders) only.
Defaults to @code{1} (which is a no-op if the unit's @code{vision-range}
is greater than or equal to 1).
@end deffn

@deffn UnitTypeProperty @code{already-seen} n%
This property is the chance to see units of this type at
the beginning of the game.
This applies only to units belonging to another side,
and on known terrain.
The effect is one-time, so if an @code{already-seen} unit changes
sides later on, other players will not see the change unless
they observe the unit for themselves.
Note that @code{see-always} does imply @code{already-seen}.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{already-seen-independent} n%
This property is like @code{already-seen},
but for independent units specifically.
Defaults to @code{0}.
@end deffn

@node Naming, Other Parameters, Method List, Initialization

@section Naming and Text Generation

@i{Xconq} can generate names for sides, units, and geographical features.

@subsection Naming Sides

Side naming is special, because several different but related names
have to be produced.

@deffn Variable @code{side-library} side-info@dots{}
This variable is a weighted list of groups of side properties,
each of which may be used to fill in a side.
@end deffn

The form of each side name entry is basically a subset of the
side's properties:
@example
([weight] ... (name "name") ... (color-scheme "colors") ...)
@end example
Each entry can include as many or as few of the attributes as desired;
any missing will be filled in from the usual defaults.
The optional @var{weight} is a number that adjusts the probability of selection
of the given side name set; it defaults to 1, and the probability is scaled
according to the sum of the weights for all the sides listed.
If any property value is a namer, then the namer will be run.
(Note that if multiple namers are specified, they cannot be guaranteed
to coordinate with each other, so you can end up with a side noun
that is inappropriate for its corresponding side name.)

@subsection Namers

Since one of the purposes of naming is to identify objects uniquely,
any name generator should be able to maintain some memory as to
what has been generated already.
The objects that do this are @dfn{namers}.

@deffn Form @code{namer} [symbol/id] method rejects@dots{}
This form defines an instance of a namer, with either the symbolic
name or numeric id.  If either matches the name or id of an existing
namer, then the old namer will be overwritten, otherwise a new one
will be created.
The @var{method} must be one of the naming methods listed below,
and @var{rejects} defines what names may not be produced (its exact
interpretation depends on the method).
@end deffn

@subsection Naming Methods

As with general synthesis, @i{Xconq} has a number of @dfn{naming methods}
available.

An implementation is free to define additional naming methods.

@deffn NamingMethod @code{random} names...@dots{}
This method picks a name from the given list of names
and removes that name from the list
@end deffn

@deffn NamingMethod @code{junky}
This method produces a gobbledy-gook name, very techy-looking.
@end deffn

@deffn NamingMethod @code{grammar} root max-length rules@dots{}
This method defines a grammar, where @var{root} is the root symbol,
@var{max-length} is a limit on the length of the generated names
(in characters),
and @var{rules} is a list of rules of the form
@example
(@var{symbol} ([sym] [weight] @var{symbol/string/list} [n] @dots{}))
@end example
@end deffn

The generation process works by substituting one of the rule's alternatives
for the symbol, starting with the root symbol.
The probability of an alternative being selected is arrived at by
adding up the optional weights @var{weight} (assuming missing weights
to be @code{1}), and choosing with a probability of the weight
divided by the total sum of weights.
Thus the weights need not add up to any particular value.

Strings get used directly.
If a symbol in the rule's chosen expansion does not appear as the
lefthand side in any rule, then it will be handled as a string,
otherwise it will be expanded in turn.
If the symbol matches a namer's name, then that namer will be
run (passing the same object??) and its result incorporated.
A list should be a list of strings and symbols, and the expansion
of each will be concatenated.

@deffn GlobalConstant @code{any}
[???]
@end deffn

@deffn GlobalConstant @code{or}
@end deffn

@deffn GlobalConstant @code{reject}
A special rule headed by @code{reject} is a list of substrings
that should not appear in a generated name; this is a convenient
way to filter out particularly unlovely results.
@end deffn

@deffn GlobalConstant @code{capitalize}
Directs capitalization of a nonterminal.
@end deffn

[text is not actually different from a namer?]

@deffn Form @code{text} [symbol/id] method rejects@dots{}
@end deffn

[elsewhere?]
@deffn GlobalVariable @code{action-messages} patterns
@end deffn

@deffn GlobalVariable @code{event-messages} patterns
@end deffn

@node Other Parameters, New Methods, Naming, Initialization

@section Other Initialization Parameters

@deffn GlobalVariable @code{edge-terrain}
This variable is the type of terrain to fill in on all the edges of a world.
The edges of a world have little or no effect on the game,
but the terrain type should be something distinctive, so that players
can recognize the edges easily.  (For instance, ice is usually a good choice
for edges, but probably not on a map of Antarctica!)
@end deffn

@section Actions in General

The parameters in this chapter define and regulate the various actions that are
available to units during a game.

Actions are always started and completed (including all of their effects)
within the same turn, and a unit can only do one of them at a time.

All actions are in theory available to all units, but the parameters
can be set so as to deny any action type to any unit type.
See the descriptions with each action type.

All action is limited by action points.
Each unit gets a certain number at the beginning of each
turn and expends them in the course of doing things.
The usual expenditure is
one point per action, but may be more, as defined for each type of action.
A unit action must always consume at least one action point.

Units can accumulate acp from turn to turn, and they can also reduce
acp below zero.

@deffn UnitTypeProperty @code{acp-per-turn} acp
This property is the basic allowance of action points that a unit gets each turn.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{acp-min} acp
This property specifies
how far into ``action debt'' a unit can go during a turn before it is prevented
entirely from acting.
A unit with acp < 1 at the beginning of a turn cannot do anything at all.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-max} acp
This property is
the maximum number of action points that a unit can save up.
The value @code{-1} means that @code{acp-max} is equal to @code{acp}.
Extra acp is silently lost.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-acp} acp
This property is
the value is the amount by which the action points for some
action can exceed the unit's currently available acp
and still allow that action.
Defaults to @code{-1}, which means enough free acp to
allow any action.
@end deffn

Note that a unit with an acp of 0 is completely unintelligent, about like
a cow patty.  Cow patties can be useful for blocking paths, hiding behind,
and suchlike, and have the advantage that once they're in place, you don't
have to manage them.  Other units will have to pick them up and put them
down, of course.

@deffn Table @code{material-to-act} u m -> n
This table is a minimum amount of @var{m} needed for @var{u} to be able to act.
The material is not consumed.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-damage-effect} xxx
@end deffn

@deffn Table @code{occupant-acp-effect} u1 u2 -> n
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{acp-per-turn-min} acp
@end deffn
@deffn UnitTypeProperty @code{acp-per-turn-max} acp
This property limits on effect of occupants, damage, etc.
Defaults to @code{1}.
@end deffn

@subsection Action Ordering

@deffn GlobalVariable @code{use-side-priority} t/f
This variable is @code{true} if the sides may only act one at a time;
otherwise, all sides and units may move simultaneously during a turn.
Defaults to @code{false}.
@end deffn

@deffn UnitTypeProperty @code{action-priority} n
This property is the order in which units of this type will act.
Higher numbers act earlier.
If the difference between the priority of one type and another
is greater than 100, then the earlier-acting units must finish acting
before the later-acting units, otherwise a player can rearrange the actual
acting order as desired.
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{actions-are-buffered} t/f
This variable is @code{true} if all the units of the same priority
must specify their actions first and then execute
them all at once,
rather than deciding and executing before the next unit gets to act.
Defaults to @code{false}.
@end deffn

@node Movement, Occupancy Parameters, Action Parameters, Unit Actions

@subsection Movement

Movement is the most common sort of action.
This section covers movement over open terrain;
the next section discusses interaction with transports.

The general theory of movement is that a unit not in a transport
crosses its current cell terrain to the edge of the cell,
crosses any border terrain, and then moves into the destination cell,
OR it moves onto connection terrain,
travels along connection terrain to the new cell, and maybe
moves off the connection.
If the unit starts in a transport, then the transport may ferry
the unit over some of the intervening terrain,
possibly as far as the unit's destination.

A unit's basic movement rate is defined by its @dfn{speed},
which is a ratio of the the unit's acp.
A speed of 100% means that the unit can potentially
enter as many cells as it has acp,
while a speed of 20% means that the unit uses at least
5 acp to enter a cell.

Movement can only succeed if several conditions are met:
the unit must be able to cross
the border terrain, the destination must be inside the world (but see below),
it must be able to exist on the terrain of the destination.

@deffn ActionType @code{move} x y z
This is the action that a unit performs to go from one location to another.
The destination must be within the @code{move-range} of the unit.
@end deffn

@deffn UnitTypeProperty @code{acp-to-move} acp
This property is the number of acp a unit uses to do one move action.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{speed} mp
This property is the basic number of movement points that a normal
undamaged unit gets at the beginning of each turn.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{speed-min} mp
This property is the worst-case speed of a unit.
Defaults to @code{0}.
@end deffn

[following needs work again]

@deffn UnitTypeProperty @code{hp-at-max-speed} mp
This property is the minimum number of hp at which the unit retains its max speed.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{hp-at-min-speed} hp
This property is the maximum number of hp at which the unit's speed is at its minimum.
Defaults to @code{0}.
@end deffn

For hp between @code{hp-at-min-speed} and @code{hp-at-max-speed},
the unit's speed will be interpolated in the obvious way.

@deffn Table @code{mp-per-occupant} u1 u2 -> n%
This table is the percent change in the speed
of type @var{u1} for each occupant of type @var{u2}.
If the basic speed of @var{u1} is @code{0},
then the multiplication is performed
as if the speed were @code{1} instead.
Defaults to @code{100}.
@end deffn

@deffn UnitTypeProperty @code{speed-max} mp
This property is the upper bound on a unit's movement in one turn.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{move-range} n
This property is the maximum distance allowed to the destination cell.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{speed-damage-effect} xxx
@end deffn

Any move between cells will cost at least one movement point.
Some mp costs may be negative, but the total mp for a move will always
be at least 1.

@deffn Table @code{mp-to-leave-terrain} u t -> mp
This table is the mp cost to leave a cell of type @var{t}.
If @var{t} is a border type, this cost is never used.
If @var{t} is a connection type, this cost is the cost of leaving the
connection terrain for the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of leaving the cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-enter-terrain} u t -> mp
This table is the mp cost to enter a cell of type @var{t}.
If @var{t} is a border type, this cost is the
cost of crossing the border.
If @var{t} is a connection type, this cost is the cost of entering the
connection terrain from the open terrain of the cell.
If @var{t} is a coating type, then this value adds to the cost
of entering the cell.
Defaults to @code{1}.
@end deffn

@deffn Table @code{mp-to-traverse} u t -> mp
This table gives the cost to travel
along a connection or border of the given type.
(note that the other costs are irrelevant if
unit starts and ends its movement on the connection).

A special type of move known as a @dfn{border slide} can occur when the
endpoints of a border touch on the start and destination cells.
Sliding works like normal movement
that happens to end up on a nonadjacent cell.
Same rules for permissibility apply.
If the value is negative, then border sliding is not possible.

Defaults to @code{1}.
@end deffn

If both enter/traverse/leave and enter/leave movement is possible,
then @i{Xconq} will automatically choose the cheapest alternative.

@deffn Table @code{mp-to-ascend} u t -> mp
@end deffn
@deffn Table @code{mp-to-descend} u t -> mp
These tables are the mp cost to go from the min possible elevation
to the max possible elevation in the world.
This is interpolated and rounded down.
@var{t} is the type of terrain being left.
Defaults to @code{0}.
@end deffn

Each unit type has a range of altitudes within which it normally operates.

@deffn Table @code{altitude-min} u t -> n
This table is the minimum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn Table @code{altitude-max} u t -> n
This table is the maximum altitude possible for each type of unit
on each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{mp-to-leave-world} mp
This property is an additional move cost to leave the world entirely.
To leave, the unit must be within its @code{move-range} of an edge,
and have sufficient mp to move into the terrain in the edge cell
designated as the destination of the move.
If the value is @code{-1}, then the unit may never leave.
Defaults to @code{-1}.
@end deffn

@deffn UnitTypeProperty @code{free-mp} mp
This property is the amount by which the move points can ``go into the red''
and still allow one more move.
Defaults to @code{0}.
@end deffn

ZOC is exerted only over units out in the open, has no effect on occupants,
unless they leave their transport.
Occupants can themselves exert a ZOC,
if @code{occupant-can-fight} is true.
ZOC applies to all units on a hostile side.

@deffn Table @code{zoc-range} u1 u2 -> dist
This table is the maximum distance at which type @var{u1}
exerts a ZOC over type @var{u2}.
A value of @code{0} means that the unit controls only its own cell,
and a value of @code{-1} means that the unit does not exert a ZOC at all.
Defaults to @code{0}.
@end deffn

@deffn Table @code{zoc-into-terrain} u t -> t/f
This table is @code{true} if the unit exerts its ZOC into terrain @var{t}.
Defaults to @code{true}.
@end deffn

@deffn Table @code{zoc-from-terrain-effect} u t -> n
Defaults to @code{100}.
@end deffn

@deffn Table @code{mp-to-enter-zoc} u1 u2 -> mp
This table specifies extra movement points needed to enter the ZOC.
@code{-1} prevents entry entirely.
Defaults to @code{-1}.
@end deffn

@deffn Table @code{mp-to-leave-zoc} u1 u2 -> mp
This table specifies extra movement points needed to leave the ZOC.
@code{-1} prevents departure entirely.
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-traverse-zoc} u1 u2 -> mp
This table specifies extra movement points needed to move within the ZOC.
@code{-1} prevents traversing entirely.
Defaults to @code{0}.
@end deffn

If multiple units exert a ZOC into the same cell, then the mp cost
is the maximum of the different ZOC costs.

Units may use up some of their materials when they move.
Consumption happens after the move action, and only for successful moves.

@deffn Table @code{material-to-move} u m -> n
This table is the amount of each material that a unit of type @var{u}
must have in order to be able to move.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-move} u m -> n
This table is the amount of each material used by a unit to do one move action.
The amount taken is independent of terrain.
If the unit has less than the required amount of any of these materials,
it is immobilized until it gets more (this is tested before each move
action; note that this does not affect any other action, including
entering and leaving transports).
Defaults to @code{0}.
@end deffn

@node Occupancy Parameters, Tech Levels, Movement, Unit Actions

@subsection Entering and Leaving Transports

Units can be inside other units, and have units inside them, in a
tree-like fashion.  There is no limit on the depth of the tree,
but most occupant-transport relationships have other limits.

@deffn ActionType @code{enter} unit
This is the action to enter the given @var{unit}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-enter-unit} acp
This property is the number of acp a unit uses to do one entry action.
Defaults to @code{1}.
@end deffn

@deffn Table @code{can-enter-independent} u1 u2 -> t/f
This table is true if a unit @var{u1} can enter an independent unit @var{u2}.
Defaults to @code{false}.
@end deffn

Entering and leaving incur mp costs as does movment,
but units with a speed of 0 may enter and leave transports.

@deffn Table @code{mp-to-enter-unit} u1 u2 -> n
This table is the extra movement points required for @var{u1}
to enter the transport @var{u2},
and vice versa (i.e. how much of transport's time is consumed by the process).
Defaults to @code{0}.
@end deffn

@deffn Table @code{mp-to-leave-unit} u1 u2 -> n
Similar to entry cost.
Defaults to @code{0}.
@end deffn

Note that these mp consumptions need not be symmetrical
between occupant and transport,
so for instance a passenger can use 2 of its mp to get on a transport,
while costing the transport only one of its mp.

@deffn Table @code{ferry-on-entry} u1 u2 -> ferry-type
@end deffn
@deffn Table @code{ferry-on-departure} u1 u2 -> ferry-type
This table specifies how much intervening terrain the unit @var{u2}
entering or leaving transport @var{u1}
will have to cross on its own (and thus incur the terrain's mp costs and
limitations).
Defaults to @code{to-dest}.
@end deffn

@deffn GlobalConstant @code{over-nothing}
This constant indicates
no ferrying, occupant must pay all costs to go to destination cell.
@end deffn

@deffn GlobalConstant @code{over-own}
This constant indicates that the
transport ferries over terrain of its own cell.
@end deffn

@deffn GlobalConstant @code{over-border}
This constant indicates that the
transport ferries over any border terrain also.
@end deffn

@deffn GlobalConstant @code{over-all}
This constant indicates that the
transport ferries to destination cell,
effectively puts occupant on middle of cell,
on connection terrain if necessary.
@end deffn

@subsection Research

Research is an action performed by a unit with the sole effect
of increasing its side's tech level.
Research cannot be performed by independent units.

@deffn ActionType @code{research} u
This is the action of researching the unit type @var{u}.
If the action is valid, then the tech level of the side
will increase.
Unit types with any tech crossover will also have their tech
levels adjusted.
@end deffn

@deffn UnitTypeProperty @code{acp-to-research} acp
This property is the number of action points used up by one research action.
Defaults to @code{0}, which disallows research.
@end deffn

@deffn Table @code{tech-per-research} u1 u2 -> .01n
This table is the gain in tech level resulting from a research action, expressed as
1/100 of a level.  Gains of less than 100 are probabilistic [should describe
this concept in general, used by several parms]
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{tech-per-turn-max} tl
This property is a ceiling on the total gain of tech level possible in one turn
for each side and this unit type.
Defaults to @code{9999}.
@end deffn

@subsection Tooling Up

There are several stages in the construction of a unit: tooling up,
creation, and completion.  Tooling up is where the building unit
prepares to build, creation is the step where the new unit comes into
existence, and completion is where the new unit is brought up to being
operational.

For the player, this is mostly automatic; if tooling must be
done first, a user command to build will generate the appropriate actions.

Once the technology has been achieved, a unit that intends to construct
other units may need to tool up.
This is expressed as @dfn{tool points} or @dfn{tp}.
Tool points start at zero, can be increased by tooling actions,
and may gradually decline (representing wear and tear on the equipment).

@deffn ActionType @code{toolup} u
This is the action of tooling up to build a unit of type @code{u}.
The result is an increase in the tp for the acting unit.
@end deffn

@deffn UnitTypeProperty @code{acp-to-toolup} acp
This property gives the number of acp needed to do a toolup action.
Defaults to @code{0}, which disallows tooling up.
@end deffn

@deffn Table @code{tp-per-toolup} u1 u2 -> tp
This table is the number of tp gained by one tooling action.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-to-build} u1 u2 -> tp
This table is the number of toolup points needed before a unit of type @var{u1}
can create or build a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-max} u1 u2 -> tp
This table is the maximum possible tooling.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-attrition} u1 u2 -> tp
This table is the number of .01 tool points automatically lost at
the end of each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{tp-crossover} u1 u2 -> n%
This table is the effective number of tool points for @var{u2} that is
guaranteed to exist, expressed as a percentage of the tool
points for @var{u1}.
[copy tech-crossover description here]
Defaults to @code{0}.
@end deffn

@subsection Creating a Unit

When a constructing unit is tooled up, the build action creates a unit
immediately and puts it in its designated location, whether inside the
unit doing the building or somewhere nearby.  This new unit, however, is
incomplete, representing the keel of the ship or the surveyor's
lines for an airstrip.  Incomplete units are thus basically skeletons,
with some unit characteristics, but unable to move or act in any way.
They also cannot have any occupants [problem for traditional bases].
Time spent on construction, then, goes into finishing these incomplete units.

@deffn ActionType @code{create-in} u unit
This action creates a new unit of type @var{u} occupying the given
unit @var{unit}.
The unit @var{unit} must have room for the new unit.
@end deffn

@deffn ActionType @code{create-at} u x y z
This action creates a new unit of type @var{u} in the open at
@var{x,y,z}.
The cell must have room for this new unit.
@end deffn

@deffn Table @code{acp-to-create} u1 u2 -> acp
This table is the acp used by @var{u1} to create a @var{u2}.
If zero, then @var{u1} cannot create a @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{separation-to-create-max} u1 u2 -> dist
This table is the maximum distance at which @var{u1} can create @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cp-on-creation} u1 u2 -> cp
This table is the completeness of a unit of type @var{u2} when
created by a @var{u1}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-to-create} u m -> n
This table is the total amount of a material type needed to create a unit.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-on-creation} u m -> n
This table is the amount of a material type consumed to create a unit.
Defaults to @code{0}.
@end deffn

@deffn Table @code{supply-on-creation} u m -> n
This table is the amount of supply that a newly created unit gets.
This supply is newly generated, does not come from anywhere else.
(Note that players could cheat by creating units, taking their supply,
and never completing them.)
Defaults to @code{0}.
@end deffn

@subsection Building a Unit

Once an incomplete unit has been created,
other units can help to complete it.

@deffn ActionType @code{build} unit
This action adds to the completeness of @var{unit}.
If the unit becomes complete, it will be given its initial supply,
acp, name, etc.
@end deffn

@deffn Table @code{acp-to-build} u1 u2 -> acp
This table is the acp used up by one build action by @var{u1}
when buiding a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cp-per-build} u1 u2 -> cp
This table is the amount of completeness of @var{u2}
added by each completion action performed by @var{u1}.
If @code{0}, then @var{u1} cannot contribute to completing @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-to-build} u m -> n
This table is the amount of each material that @var{u} must have
in order to build anything.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-build} u m -> n
Defaults to @code{0}.
@end deffn

@deffn Table @code{separation-to-build-max} u1 u2 -> dist
This table is the maximum distance allowed between a unit @var{u1} and the
incomplete unit @var{u2} it is working on.
Defaults to @code{0}, which requires the two units to be in
the same cell.
@end deffn

At a given point, incomplete units can make progress towards
completion on their own.  This is automatic because incomplete
units are unable to act, and occurs at a constant specified rate.

@deffn UnitTypeProperty @code{cp-to-self-build} cp
This property is the minimum completeness of the unit necessary before it
can work on itself.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{cp-per-self-build} cp
This property is the completeness added each turn when a unit works on itself.
Defaults to @code{0}.
@end deffn

@deffn Table @code{supply-on-completion} u m -> n
This table is the minimum amount of supply guaranteed to a newly completed
unit.  If not already available to the unit, it will be newly generated.
Defaults to @code{0}.
@end deffn

@node Repair, Producing Materials, Construction, Unit Actions

@subsection Repair

Units can restore their own and each other's hp by doing repairs.
Repair requires a repair action.
The action points for this action
are taken from both the unit being repaired and
the repairer (using the same table @code{acp-to-repair}).
When a unit repairs itself, the action cost is counted once only.

@deffn ActionType @code{repair} unit
This is the action of repairing the given @var{unit}.
@end deffn

@deffn Table @code{acp-to-repair} u1 u2 -> acp
This table is the number of action points used up
by @var{u1} doing one repair action on @var{u2}.
Defaults to @code{0}, which disallows the action.
@end deffn

@deffn Table @code{hp-per-repair} u1 u2 -> .01hp
This table is the hundredths of a hp that a single repair action by @var{u1}
restores to @var{u2}.
The fraction of this over 100 is added to hp directly,
while the < 100 fraction is added probabilistically.
Defaults to @code{0}.
@end deffn

Materials may be needed and/or consumed during repair.
The materials will be taken from the
unit being repaired, then from the repairer.

@deffn Table @code{material-to-repair} u m -> .01n
This table is the amount of each material needed for one repair action.
As with repair, the < 100 part is average, and > 100 is guaranteed.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-per-repair} u m -> .01n
@end deffn

The repairing unit must also not be too damaged itself to do repairs.

@deffn Table @code{hp-to-repair} u1 u2 -> hp
This table is the minimum hp level required of @var{u1} to repair @var{u2}.
If less, then @var{u1} is too damaged to do any repairing.
Defaults to @code{1}, which allows repair always.
@end deffn

@node Producing Materials, Transferring Supply, Repair, Unit Actions

@subsection Producing Materials

Units can produce materials by explicit action.

@deffn ActionType @code{produce} m n
This action results in a quantity @var{n} of material @var{m}
coming into existence.
@end deffn

@deffn Table @code{acp-to-produce} u m -> acp
This table is the acp used up by one @code{produce} action.
Defaults to @code{0}.
@end deffn

@deffn Table @code{material-per-production??} u m -> n
This table is the amount of material produced by @var{u}
when acting to produce type @var{m}.
Defaults to @code{0}.
@end deffn

@node Transferring Materials, Changing Sides, Producing Materials, Unit Actions

@subsection Transferring Materials

Although most movement of materials between units happens automatically
(see backdrop economy description, section xxx),
players can also do it explicitly.
Players can both take materials from other units, and give a unit's
materials to others.

@deffn ActionType @code{transfer} unit m n
This is the action of transferring supply to the given unit @var{unit}.
The desired amount is @var{n};  if @var{m} is a valid material type,
then only that type will be transferred, otherwise the action will
transfer all types of materials possible.
The actual transfer amounts may be less than @var{n}.
[If @var{unit} is NULL, then is equiv to discarding material?]
@end deffn

@deffn Table @code{acp-to-unload} u1 m -> acp
@end deffn
@deffn Table @code{acp-to-load} u1 m -> acp
These tables are the number of action points used up by one material transfer
action from @var{u1} to @var{u2}.
The amount is independent of the material type being transferred.
If either value is @code{0}, then the material cannot be transferred.
Defaults to @code{0}.
@end deffn

@deffn Table @code{unload-max} u1 m -> n
@end deffn
@deffn Table @code{load-max} u2 m -> n
These two tables determine how much of material @var{m} can be transferred out
of a unit of type @var{u1} and into one of type @var{u2}
in one transfer action.
The actual quantity transferred by the action
is the minimum of these two values.
A value of @code{0} disallows manual transfer.
Both default to @code{-1}, which allows any amount to be transferred.
@end deffn

@node Changing Sides, Disbanding, Transferring Supply, Unit Actions

@subsection Changing Sides

@deffn ActionType @code{change-side} side
This is the action of changing the actee's side to @var{side}.
The @var{side} can be any allowable side, and the actee
may be any unit controlled by the actor's side.
@end deffn

@deffn UnitTypeProperty @code{acp-to-change-side} acp
If the value of this property is greater than 0,
then this type of unit can be ordered to change to another given side.
The type must also be allowed to be on the new side.
Defaults to @code{0}.
@end deffn

@node Disbanding, Organization, Changing Sides, Unit Actions

@subsection Disbanding

Disbanding is the voluntary and controlled destruction of a unit,
performed by the unit itself or another unit.
A disbanded unit always vanishes, rather than changing to its
@code{wrecked-type}.

@deffn ActionType @code{disband} unit
This is the action of removing hp from @var{unit}.
The unit will vanish if all its hit points are gone.
@end deffn

@deffn Table @code{acp-to-disband} u1 u2 -> acp
This table is the number of action points used by the unit @var{u1}
to do a disband action on unit @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{hp-per-disband} u1 u2 -> hp
This table is the number of hp lost in a disband action
performed by @var{u2}.
Defaults to @code{0}, which disallows disbanding.
@end deffn

A disbanded unit can be scavenged for materials.

@deffn Table @code{supply-per-disband} u m -> n%
This table is the percentage of the unit's supply that is recovered
from a single disband action.
If the value is zero, then the unit's supply will not be
recovered by the disbanding process, and be lost permanently.
If any supply remains when the unit's hp is 0, then that
supply will be lost also.
Defaults to @code{100}, which means that the entire supply
will be recovered on the first disband action.
@end deffn

Note that if an essential supply is 100% recovered before the unit
is completely disbanded, then it may die from starvation first.
A partly-disbanded unit may still acquire supply
from nearby units, via the backdrop economy.

@deffn Table @code{recycleable-material} u m -> n
This table is the quantity of each type of material that becomes available
when a unit is completely disbanded.
The materials go to transports, occupants, and nearby units, in that order.
Any materials exceeding capacities of these units will be discarded.
These materials become available only when the unit vanishes.
Defaults to @code{0}.
@end deffn

@node Organization, Combat, Disbanding, Unit Actions

@subsection Transferring Parts

Units of variable size can transfer parts of themselves to other
units, or create a new unit.

@deffn ActionType @code{transfer-parts} n unit
This action moves @var{n} parts of the actee to @var{unit},
or creates a new unit if @var{unit} is omitted.
If @var{n} is negative, this takes from @var{unit} instead.
If the action takes all the parts of any involved unit,
then it vanishes.
@end deffn

@deffn UnitTypeProperty @code{acp-to-transfer-part} acp
Defaults to @code{0}.
@end deffn

@subsection Changing Type

@deffn ActionType @code{change-type} u
@end deffn

@deffn Table @code{acp-to-change-type} u1 u2 -> acp
Defaults to @code{0}.
@end deffn

@node Combat, Detonation, Organization, Unit Actions

@subsection Combat

Xconq combat is somewhat abstract; the attacking player decides what sort
of attack to mount and perhaps when to retreat, but all else happens
automatically.

Combat may last longer than a single action;
it is then called a @dfn{battle} and divided into @dfn{rounds}.
The battle exists until one participant has a commitment of zero.
Units in a battle need not attack, and no damage will occur if none do so,
but they cannot move away until no longer committed.

The attacker/defender distinction applies only to a single action.

@deffn ActionType @code{attack} unit [commitment]
This action is a direct attack on the given @var{unit}.
The @var{unit} must be known to the attacking unit's side.
@end deffn

@deffn ActionType @code{overrun} x y z [commitment]
Overruns are a sort of combined attack/capture/move action.
The basic theory of an overrun is that the actor will attack,
capture, or co-occupy the given destination.
The exact effects depend on the types and sides of units in the destination.
@end deffn

@deffn Table @code{acp-to-attack} u1 u2 -> acp
This table is the number of action points used up by the attacker.
Defaults to @code{1}.
@end deffn

@deffn Table @code{acp-to-defend} u1 u2 -> acp
This table is the number of action points used up by the defender.
Defaults to @code{1}.
@end deffn

@deffn Table @code{attack-range-min} u1 u2 -> dist
This table is the minimum distance at which a unit can attack another.
Defaults to @code{0}.
@end deffn

@deffn Table @code{attack-range} u1 u2 -> dist
This table is the maximum distance at which a unit can attack another.
Defaults to @code{1}.
@end deffn

One round of combat consists of an attack, a reaction,
and a calculation of effects.

The defender's reaction is completely automatic, and occurs as part of the
attack action.  The defender's side does not get a chance to
decide what to do until the next round,
although doctrine can constrain the randomness somewhat.

@deffn Table @code{attack-commit-min??} u1 u2 -> n%
@end deffn
@deffn Table @code{defend-commit-min??} u1 u2 -> n%
These tables are the minimum limits on the initial commitment to a battle.
Defaults to @code{0}.
@end deffn

@deffn Table @code{attack-commit-max??} u1 u2 -> n%
@end deffn
@deffn Table @code{defend-commit-max??} u1 u2 -> n%
These tables are the maximum limits on the initial commitment to a battle.
Defaults to @code{100}.
@end deffn

@deffn Table @code{attack-commit-up-max??} u1 u2 -> n%
@end deffn
@deffn Table @code{defend-commit-up-max??} u1 u2 -> n%
@end deffn
@deffn Table @code{attack-commit-down-max??} u1 u2 -> n%
@end deffn
@deffn Table @code{defend-commit-down-max??} u1 u2 -> n%
These tables are the maximum limits on the change to commitment to a battle.
Defaults to @code{100}.
@end deffn

@deffn Table @code{surrender-chance-per-attack} u1 u2 -> n%
This table is the chance that u2 will surrender to u1
immediately upon being attacked.
Defaults to @code{0}.
@end deffn

@deffn Table @code{withdraw-chance-per-attack} u1 u2 -> n%
This table is the chance that u2 will retreat from u1
immediately upon being attacked.
Defaults to @code{0}.
@end deffn

In an overrun action,
if all the defending units are destroyed,
the attacker has sufficient acp and mp,
and the destination is safe to enter,
then the attacker can move into the defenders' cell.

Firing is a kind of attack that can take place at a distance,
involves no commitment or counterattack,
and for which the type of ammo may be selected.

@deffn ActionType @code{fire-at} unit [m]
This is the action of firing at a given @var{unit}.
If @var{m} is given, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn

@deffn ActionType @code{fire-into} x y [z] [m]
This is the action of firing into the cell at @var{x,y}.
If @var{z} is given, then the fire will be concentrated
on units at that elevation.
If @var{m} is given, then that type will be used as ammo,
otherwise all available types will be used together.
@end deffn

@deffn UnitTypeProperty @code{acp-to-fire} acp
If this property is greater than 0, this type may attack by firing.
Defaults to @code{0}.
@end deffn

@deffn Table @code{acp-to-be-fired-on} u1 u2 -> acp
This table is the acp lost when a unit is being fired upon.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{range} dist
This property is the maximum distance to which a unit can fire.
Defaults to @code{1}.
@end deffn

@deffn UnitTypeProperty @code{range-min} dist
This property is the minimum distance to which a unit can fire.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{elevation-at-max-range} dist
[elaborate calc to interpolate while rising and falling, basically
approximating a parabola]
@end deffn

@deffn Table @code{hit-falloff-range} u1 u2 -> n
@end deffn

@deffn Table @code{hit-at-max-range-effect} u1 u2 -> n
@end deffn

Both attack and fire combat calculate hits in the same way.

@deffn Table @code{hit-chance} u1 u2 -> n%
This table is the basic chance that a unit of type @var{u1} will
actually hit a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{attack-terrain-effect} u1 t -> n%
@end deffn
@deffn Table @code{defend-terrain-effect} u2 t -> n%
These tables specify the
effect of attacker's and defender's respective terrains on
@code{hit-chance}.
These chances are multiplied with the basic hit chance.
Default to @code{100}.
@end deffn

@deffn Table @code{cxp-hit-effect} u1 u2 -> n
@end deffn
@deffn Table @code{cxp-damage-effect} u1 u2 -> n
@end deffn
@deffn Table @code{cxp-material-effect} u1 u2 -> n
@end deffn

@deffn Table @code{friendly-hit-chance} u1 u2 -> n%
This table is the chance that a unit @var{u2} on the attacker's side will
be hit accidentally during an @code{overrun} or @code{fire-into}
action.
Defaults to @code{0}.
@end deffn

[also have surrender/withdraw upon hit with no damage?]

@deffn Table @code{damage} u1 u2 -> hp
This table is the basic amount of damage caused by a successful attack.
The value is a ``dice spec'' [explain somewhere]
Defaults to @code{1}.
@end deffn

The damage in an attack is always prorated by commitment;
the table value is for attacks at full commitment.

@deffn Table @code{hp-min} u1 u2 -> hp
This table is the lowest hp possible for @var{u1} from attacks by @var{u2}.
Further attacks by @var{u2} are still valid, but have no effect.
Defaults to @code{0}.
@end deffn

You can set a unit to use a material as ammo.

@deffn Table @code{consumption-per-attack} u1 m -> n
@end deffn
@deffn Table @code{hit-by} u2 m -> n
These tables specify material consumption in combat.
For each material @code{m}, the min of these two values is the amount
of u1's supply used up in an attack on u2.
Both default to @code{0}.
@end deffn

@deffn Table @code{material-to-fight} u m -> n
This table is a minimum of each material that is necessary to either
attack or defend.
Defaults to @code{0}.
@end deffn

Transports can protect their occupants, or pass hits through.

@deffn Table @code{protection} u1 u2 -> n%
@end deffn

@deffn Table @code{ablation} u1 u2 -> n%
This table is the amount of the hit that gets passed through
to the transport's occupants.
Defaults to @code{100}.
@end deffn

@deffn Table @code{stack-protection} u1 u2 -> n%
@end deffn

@deffn Table @code{stack-ablation} u1 u2 -> n%
@end deffn

[transport's destruction may leave occupants stranded on hex,
could do some sort of auto-escape or die if terrain is hostile
use ferry-on-leave to decide]

[some occupants (like armor) should be able to take hits first,
then pass to transport - total effect is armor -> unit -> occupants]

@deffn Table @code{ambush-chance} u1 u2 -> n%
If @var{u1} attempts to move into a cell containing @var{u2},
then a) if can't co-occupy, this table is the chance that @var{u1}
gets a chance to attack at improved odds(?), or if b) if can
co-occupy, then @var{u1} will enter the cell, then be attacked
as in a).  The ambusher's plan can flag whether the unit
will take ambush opportunities or not.
@end deffn

Several other side-effects of combat may also be defined.

@deffn Table @code{theft-chance-per-attack??} u1 u2 -> n%
@end deffn

@deffn Table @code{stealable-material??} u m -> n
@end deffn

@deffn Table @code{loss-per-attack??} u1 u2 -> n%
@end deffn

@deffn Table @code{retreat-chance} u1 u2 -> n%
This table is the chance that @var{u2} will retreat if hit by @var{u1}.
Defaults to @code{0}.
@end deffn

[need general defns for who moves and when during combat rounds]
[could potentiall acquire additional acp if move is discretionary,
also get a level of flexibility about future commitment]

[need combat's effect on tooling? uu_tp_hit_effect, can be positive
or negative (being hit helps recruiit soldiers)
just hit tp randomly as percentage of hp]

Finally, a unit can attempt to capture another unit directly.
This means that the unit's side changes to that of the capturing unit,
but with no other consequences.

@deffn ActionType @code{capture} unit
This is the action of capturing the given @var{unit}.
@end deffn

@deffn Table @code{acp-to-capture} u1 u2 -> acp
This table is the number of acp used up by a @code{capture} action.
Defaults to @code{0}, which disallows capture.
@end deffn

@deffn Table @code{capture-chance} u1 u2 -> n%
This table is the basic chance for @var{u1} to capture @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{scuttle-chance} u t -> n%
This table is the chance that a unit whose capture is guaranteed will disband
itself entirely instead.  Scuttling is destructive, so unit changes to
@code{wrecked-type}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-escape-chance} u1 u2 -> n%
This table is the chance that an occupant @var{u1} will escape during the capture
of a unit of type @var{u2}.
Occupants that do not escape are either captured themselves or destroyed,
depending on their type and the capturing unit's side.
Defaults to @code{0}.
@end deffn

@deffn Table @code{hp-to-garrison} u1 u2 -> n
This table is the number of hp that will be taken from the capturing
unit @var{u1} in order to guard a captured @var{u2}.
If the amount is the unit's full hp, then the unit will vanish
and any occupants will be distributed to the captured unit, to open
terrain, or will vanish themselves if there is no other option.
Defaults to @code{0}.
@end deffn

@c @deffn Word {@var{bool unit2 unit @code{bridge}}}
@c True if the unit type @var{unit2} can be captured by another unit
@c @var{unit}, even across
@c impassable terrain.
@c @end deffn

@deffn UnitTypeProperty @code{attack-up-penalty??} n
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{attack-down-penalty??} n
Defaults to @code{0}.
@end deffn

Combat experience affects a unit's ability to hit,
and the seriousness of hits on itself.

@deffn Table @code{cxp-hit-plus-max??} u1 u2 -> n%
This table is the maximum hit modifier for attacker unit.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cxp-hit-minus-max??} u1 u2 -> n%
This table is the maximum hit modifier for defender unit.
Defaults to @code{0}.
The actual hit probability equals the basic hit probability, plus
@code{experience-hit-plus-max} times fractional experience (i.e.
experience divided by maximum experience) of the attacking unit, minus
@code{experience-hit-minus-max} times fractional experience of the
defending unit.
@end deffn

@deffn Table @code{cxp-per-combat} u1 u2 -> cxp
This table is the number of combat experience points gained by @var{u1}
by surviving a combat round with @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{cxp-per-capture} u1 u2 -> ep
This table is the number of combat experience points gained by @var{u1}
by capturing @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{cxp-on-capture-effect} n
This property gives the change in a unit's cxp due to being captured,
expressed as a multiplier.
Defaults to @code{100}.
@end deffn

@node Detonation, Terrain Alteration, Combat, Unit Actions

@subsection Detonation

Detonation is a sort of cross between disbanding and combat,
but is a distinct kind of action.
The action specifies the location of the detonation,
which may be in the unit's cell or an adjacent one.
A unit that detonates either loses hp or changes to its
@code{wrecked-type}.
(Note that one could then have a unit that detonates multiple times.)
It also effectively hits every unit in the vicinity.

@deffn ActionType @code{detonate} x y [z]
This action detonates the actee at the given location @var{x,y,z}.
@end deffn

@deffn UnitTypeProperty @code{acp-to-detonate} acp
This property is the number of action points used by one detonate action.
Defaults to @code{0}, which disallows detonation.
@end deffn

@deffn UnitTypeProperty @code{hp-per-detonation} hp
This property is the number of hp lost in each detonation.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-damage-at} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in the same cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-damage-adjacent} u1 u2 -> hp
This table is the severity of @var{u1}'s hit on a unit @var{u2} in an adjacent cell.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-range} u1 u2 -> dist
This table gives the range of effect from detonation of @var{u1}.
The severity falls off according to the inverse square law
extrapolated from the adjacent cell damage.
(1/4 severity at range 2, 1/9 at 3, etc.)
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonate-on-hit} u1 u2 -> n%
This table is the chance that a hit on @var{u1}
by a unit of type @var{u2} will cause it to detonate (once).
Noncombat reductions in hp, such as attrition, have no effect.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{detonate-on-death} n%
This property is the chance that if this type is about to die from a combat hit,
it will detonate (once) first.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonate-on-capture} u1 u2 -> n%
This table is the chance that this type will detonate before being captured
by @var{u2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonate-on-approach} u1 u2 -> dist
When a unit of type @var{u2} on a non-trusted [?] side
appears at a distance of @var{dist}
or less, then @var{u1} will detonate.
Defaults to @code{0}.
@end deffn

@deffn Table @code{detonation-accident-chance} u t -> n.f%
This table is the chance that the unit will detonate spontaneously.
This is checked once/turn. [where/when?]
Defaults to @code{0}.
@end deffn

[should rethink??]

@deffn Table @code{damaged-terrain} t1 t2 -> n
@end deffn

@node Terrain Alteration, Type Alteration, Detonation, Unit Actions

@subsection Altering Terrain

@deffn ActionType @code{alter-terrain} x y t
This action changes the type of the cell at @var{x,y} to @var{t}.
@end deffn

@deffn ActionType @code{add-terrain} x y dir t
This action adds a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn

@deffn ActionType @code{remove-terrain} x y dir t
This action removes a connection or border of type @var{t}
to the cell at @var{x,y}, in direction @var{dir}.
@end deffn

@deffn Table @code{acp-to-add-terrain} u t -> n
@end deffn
@deffn Table @code{acp-to-remove-terrain} u t -> n
For auxiliary terrain types, these tables are the costs to add or remove.
For cell terrain, the costs of removing the old type and adding the
new type are added together.
@end deffn

@deffn Table @code{alter-terrain-range} u t -> n
This table is the maximum distance at which a unit can alter terrain @var{t}.
Defaults to @code{0}, which means that the unit can change only the
terrain in its own cell.
@end deffn

At present, all sides that have seen the terrain once will be informed
about any changes.

@section Environmental Computation

This section describes how to set up backdrop computations
on the state.

@subsection Random Parameters

Environmental conditions may be computed randomly.

@deffn TerrainTypeProperty @code{temperature-average} n
This property is the average temperature for each type of terrain.
Defaults to @code{0}.
@end deffn

@deffn TerrainTypeProperty @code{temperature-variability} n
This property is the amount of totally random variation
in the temperature in each cell.
Defaults to @code{0}.
@end deffn

[random clouds, etc]

[have random storms, increase chance in weather extrema if they occur]

The primary effect of clouds is to make things harder to see.

@deffn UnitTypeProperty @code{cloud-vision-effect} xxx
@end deffn

@subsection Wind Parameters

@deffn TerrainTypeProperty @code{wind-force-average}
@end deffn

@deffn TerrainTypeProperty @code{wind-force-variability}
@end deffn

@deffn TerrainTypeProperty @code{wind-variability}
@end deffn

@deffn GlobalVariable @code{wind-mix-range}
This variable is the radius out to which winds interact.
If 0, then winds in adjacent cells can vary independently
of each other, and do not interact in any way.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{wind-speed-effect} xxx
@end deffn

@deffn UnitTypeProperty @code{wind-angle-effect} xxx
@end deffn

@subsection Season Parameters

@deffn WorldProperty @code{year-length} n
This property is the number of turns in an annual cycle.
If less than @code{2}, then no seasonal effects will be calculated.
Defaults to @code{0}.
@end deffn

@deffn WorldProperty @code{day-length} n
This property is the number of turns in a single day.
If less than @code{2}, then day and night will not be calculated.
Defaults to @code{0}.
@end deffn

Note that @code{year-length} and @code{day-length} are
completely independent of each other, and it is possible
to have days that are longer than years.

@deffn AreaProperty @code{initial-year-part} n
This property is the season of the first turn in the game.
Defaults to @code{0}.
@end deffn

@deffn AreaProperty @code{initial-day-part} n
This property is the hour of the first turn in the game.
Defaults to @code{0}.
@end deffn

[need amount of daylight, twilight, etc]

@subsection Varying Activity with the Season

@deffn UnitTypeProperty @code{acp-at-midsummer} acp
This property is the extra acp that the unit gets at polar midsummer.
This property is added to the basic @code{acp-per-turn}.
Defaults to @code{0}.
@end deffn

@deffn UnitTypeProperty @code{acp-at-midwinter} acp
This property is the loss of acp at polar midwinter.
This property is subtracted from the basic @code{acp-per-turn}.
Defaults to @code{0}.
@end deffn

These values are interpolated according to the cycle's position
and the unit's latitude.  Both values may be negative.

@subsection Varying Temperature with the Season

To make the temperature vary with the season, you set the high and low
values at the equator and north pole, where the low is always at midwinter
and the high is always at midsummer.  @i{Xconq} interpolates on both the
latitude and season to arrive at the average temperature of a location.
Note that the southern hemisphere will have seasons equal but
opposite to those in the north (thus there are no ``south pole parameters'').

@deffn GlobalVariable @code{temperature-at-midsummer}
@end deffn
@deffn GlobalVariable @code{temperature-at-midwinter}
@end deffn

[design chapter should mention values 40, 20, 5, -40 make earthlike]

@deffn TerrainTypeProperty @code{temperature-moderation-range} distance
This property is the radius of the area whose raw temperatures will be averaged
to get the actual temperature.
This can be very slow, so only values of 0 (no averaging)
and 1 (average with adjacent cells) are recommended.
Defaults to @code{0}.
@end deffn

The defaults for these values yield reasonable values for Earth-like
worlds, assuming the temperature is Centigrade.

@subsection Weather Parameters

While the seasons change relatively slowly and predictably,
weather can change drastically from turn to turn.
@i{Xconq} weather is based on a daily cycle of heating and cooling
plus the movement of water vapor.


Weather and seasons can be defined completely independently of each other.
The weather model assumes a constant basic temperature, set from
summer-equator if the season model is not being used.

Atmospheric vapor is modelled by having a vapor quantity in each cell
[define a layer for this].
Vapor originates with evaporation from terrain,
moves around with changing winds and air pressure,
and high levels result in clouds, rain, and snow.

@section Environmental Effects

The environmental conditions include temperature, coatings such as snow,
and atmospheric conditions.

[specify these]

The current environmental conditions in each cell
[or in world as a whole? or calc by regions?]
derive from a combination of three calculations:
random, seasons, and weather.

@subsection Coating Effects

[effects of coating should be increased attrition, decreased
productivity, decreased activity and mobility]

@subsection Effects of Temperature on Units

The cell's temperature affects units only if it is outside the unit's
``comfort zone''.
Uncomfortable units have increased attrition, reduced acp and mp.
[extra consumption?]

@deffn UnitTypeProperty @code{survival-zone-min} n
@end deffn
@deffn UnitTypeProperty @code{survival-zone-max} n
These properties specify the temperatures above and below which the unit dies
(vanishes?).
Default to @code{-9999} and @code{9999}, respectively.
@end deffn

@deffn UnitTypeProperty @code{comfort-zone-min} n
@end deffn
@deffn UnitTypeProperty @code{comfort-zone-max} n
These properties are the temperatures within which which the unit is comfortable.
Default to @code{-9999} and @code{9999}, respectively.
@end deffn

Transports can protect their occupants from temperature extremes.

@deffn Table @code{temperature-protection} u1 u2 -> t/f
@end deffn

[any effects of temperature on material production by units and cells?]

[specify temperature attrition, generic effect, etc]

@subsection Effects of Lighting on Units

@deffn Table @code{night-acp-effect} u t -> n
This table is the multiplier for unit's acp at night in each type of terrain.
Defaults to @code{100}.
@end deffn

@deffn Table @code{night-vision-effect} u t -> n
This table is the multiplier for unit's vision at night in each type of terrain.
Defaults to @code{100}.
@end deffn

@node Economy, , Random Occurrences, Backdrop Definition

@section Economy

The following parameters control the automatic production, distribution, and
consumption of materials by units and by cells.

@subsection Unit Production and Consumption

Units can be set to always produce some amount of material without
taking explicit action.

@deffn Table @code{base-production} u m -> n
This table is the basic amount of each material @var{m}
produced by a unit of type @var{u} in each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{occupant-production} u m -> n
This table is the base production when unit is an occupant.
Defaults to @code{0}.
@end deffn

@deffn Table @code{productivity} u t -> n%
This base is the percentage productivity of a unit on a type of terrain.
This is multiplied with the basic production rate to get actual material
production, so productivity of @code{0} completely disables production on
that terrain type, and productivity of @code{100} yields the rate
specified by @code{base-production}.
Defaults to @code{100}.
@end deffn

@deffn Table @code{productivity-min} u m -> n
@end deffn
@deffn Table @code{productivity-max} u m -> n
These tables are the
lower and upper bounds on actual production after multiplying by
productivity.
Default to @code{0} and @code{9999}, respectively.
@end deffn

@deffn Table @code{base-consumption} u m -> n
This table
sets the amount of materials consumed by the unit in a turn, even if it
doesn't move or do anything else.
Defaults to @code{0}.
@end deffn

@deffn Table @code{hp-per-starve} u m -> hp
If the unit runs out of a material that it must consume,
this table specifies how many hp it will lose each turn that it is starving.
If starving for several reasons, loss is max of starvation losses,
not the sum.
Defaults to @code{0}.
@end deffn

@deffn Table @code{consumption-as-occupant} u m -> n%
This table is the consumption by a unit of type @var{u1} when it is
an occupant of @var{u2}, expressed as a percentage
of its @code{base-consumption}.
This is useful for
units such as planes which always consume fuel in the air but not on
the ground.
Defaults to @code{100}.
@end deffn

@subsection Terrain Production and Consumption

Materials produced by cells can be redistributed and also taken up
by units.

@deffn Table @code{terrain-base-production} t m -> n
This table is the amount of each material produced by a cell of the given
type in each turn.
Defaults to @code{0}.
@end deffn

@deffn Table @code{terrain-base-consumption} t m -> n
This table is the amount of material consumed by a cell each turn.
If insufficient material is available, then the terrain may change type.
Defaults to @code{0}.
@end deffn

@deffn Table @code{change-on-exhaustion-chance} t m -> n%
This table is the chance that a cell will change to its exhausted type.
@end deffn

@deffn Table @code{terrain-exhaustion-type} t1 m -> t2
If @var{t2} is @code{non-terrain},
then this table says that any cell with terrain @var{t1}
that is ``exhausted'' will change to @var{t2}.
If several materials are
exhausted in the same turn, then the lowest-numbered material type
will determine the new terrain type.
Defaults to @code{non-terrain}.
@end deffn

@deffn Table @code{people-base-consumption} m1 m2 -> n
This table is the base consumption per turn
by people of type @var{m1} of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn

@deffn Table @code{people-base-production} m1 m2 -> n
This table is the people of type @var{m1} base production per turn
of each other material type @var{m2}.
Defaults to @code{0}.
@end deffn

@subsection Supply Lines

In real life, material production and consumption rarely occur in the same place
at the same time.
For some games, the player must transfer materials
manually, by loading and unloading from units.
However, this can be time-consuming and difficult,
and is best reserved for scarce and/or
valuable materials.
For more common materials, @i{Xconq} provides @dfn{supply lines}.

@deffn Table @code{in-length} u1 m -> dist
@end deffn
@deffn Table @code{out-length} u2 m -> dist
These two tables are used together to determine the length of supply lines
between units.  The given type of material can only be transferred from
unit type @var{u1} to unit type @var{u2}
if the distance is less than the minimum of
the @code{in-length} of @var{u1} and the @code{out-length} of @var{u2}.
For instance, the @code{in-length} for a fighter's fuel might be 3 cells,
while the @code{out-length} of fuel from a city is 4 cells.
Then the fighter will be constantly supplied with fuel
when within 3 cells of a city.
If the fighter's out-length is -1, it will never
transfer any fuel to the city.
An in- or out-length of @code{0} means that the two units must be
in the same cell,
while a negative length disables the automatic transfer completely.
Long @code{out-length} lines should be used sparingly,
since the algorithm uses the @code{out-length} to
define a radius of search for units to be resupplied.
Both default to @code{0}.
@end deffn

@deffn Table @code{supply-move-rate??} t m -> n
This table says how much of material @var{m} can be moved through terrain @var{t}
(cell, border, or connection) in each material transfer action.
The actual limit is the minimum of all cells and borders
along the supply route.
A value of @var{-1} allows any quantity to go through.
@end deffn

@deffn Table @code{supply-interdiction??} u m -> n%
This table is the reduction of supply due to the presence of an enemy unit of the
given type on the supply line.
A value of @code{100} means that the unit has no effect on supply movement,
a value of @code{0} means that the supply line is completely cut.
Defaults to @code{0}.
@end deffn

@subsection Trade Between Units/Sides

@subsection Trade

To move materials automatically between cells,
you must define the demand and supply relationships,
as well as the rate and distance that materials can move.

Demand for a material originates with consumption and
construction needs, issuing either from a side or from
some other part of the economy.

@subsection Taxation

A side can set a taxation rate, which is the amount of material
that will be taken from the cell-based economy and given to units
on that side.

Taxes may be negative, which will have the effect of returning
materials from units back to cells.

Taxation is the last step in economic calculations.

@subsection Material Conversion

Some types of materials can be converted or combined into other types
of materials.

[do by letting production vary according to consumption?]

[in general, should distinguish productive from consumptive units,
specify as limits on in/out for each rtype]

@section Random Events

[check validity of random event list after loading]

@deffn GlobalVariable @code{random-events} method-list
This variable is a list (actually a set) of random event methods
that will be run at the end of each turn.
@end deffn

@subsection Terrain Attrition

Attrition is the automatic loss of hit points due to being in certain types
of terrain.

@deffn Method @code{attrition-in-terrain}
For every unit not in a transport,
this method computes the chance to lose hit points,
then damages the unit accordingly.
This method runs once per turn.
@end deffn

@deffn Table @code{attrition} u t -> .01hp
This table is the rate of loss of hp per turn.
The terrain used is cell or connection terrain as appropriate for
the unit's position.
Defaults to @code{0}.
@end deffn

@subsection Terrain Accident

Accidents result in the damage or disappearance of a unit in the open
in some kinds of terrain.

@deffn Method @code{accidents-in-terrain}
For every unit not in a transport,
this method computes the chance to be hit or to vanish completely.
This method runs once per turn.
@end deffn

@deffn Table @code{accident-hit-chance} u t -> .01n%
This table is the chance of the unit being hit while in the given terrain.
Defaults to @code{0}.
@end deffn

@deffn Table @code{accident-damage} u t -> hp
This table is the hp that will be lost in an accident.
Defaults to @code{0}.
@end deffn

@deffn Table @code{accident-vanish-chance} u t -> .01n%
This table is the chance of the unit simply vanishing while in the given terrain.
Defaults to @code{0}.
@end deffn

@subsection Revolt

Revolt is a spontaneous change of side,
occurring in place of a side-given unit action.
The new side may be none (independence) or another side.
[only if other side wants it?] [50/50 chance?]

@deffn Method @code{units-revolt}
For each completed unit, this method decides whether the unit revolts,
then changes its side.
@end deffn

@deffn UnitTypeProperty @code{revolt-chance} n.01%
This property is the chance for the unit to revolt spontaneously.
Defaults to @code{0}.
@end deffn

@subsection Surrender

@deffn Method @code{units-surrender}
@end deffn

@deffn Table @code{surrender-chance} u1 u2 -> n
This table is the chance that a unit of type @var{u1} will change its side
to match the side of a unit @var{u2} that is within the @code{surrender-range}
for the two types.
Defaults to @code{0}.
@end deffn

@deffn Table @code{surrender-range} u1 u2 -> dist
This table is the distance out to which a unit of type @var{u1}
will surrender to a unit of type @var{u2}.
Defaults to @code{0}.
@end deffn

@node Random State, Chrome, Populations, Miscellany

@section The Random State

It is occasionally useful to restart the random number generator
consistently.

@deffn GlobalVariable @code{random-state} n
This variable is the state of the random number generator.
If this is not used, then the initial state of the random number
generator will be set in a system-dependent way.
@end deffn

@section Default Display Style

The exact style of display depends on the user interface and
on user preferences,
but for some games, you may want to encourage a particular style
by making it be the default.

@deffn GlobalVariable @code{unseen-char} str
This variable is the name of a character that will be used to
represent unexplored terrain.
Defaults to @code{" "}.
@end deffn

@deffn GlobalVariable @code{unseen-color} str
This variable is the name of a color that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{unseen-image-name} str
This variable is the name of an image that will be used to
represent unexplored terrain.
Defaults to @code{""}.
@end deffn

@deffn GlobalVariable @code{grid-color} str
This variable is the name of a color to use to draw the
cell-separating grid.
Defaults to @code{""}.
@end deffn

@section Dates and Time

You can make @i{Xconq} display game time as a calendar date,
rather than as a simple turn number.

@deffn GlobalVariable @code{calendar} xxx
This variable is the description of the calendar type that will be used.
If @code{"none"}, then turns will be reported numerically starting
from @code{1}.  If @code{"usual"}, then our present-day Gregorian
calendar will be used.
(Other calendars may be supported in the future.)
Defaults to @code{()}.

This is how long a turn is, in terms of the calendar.  For instance,
if the usual calendar is being used, then a time measure of @code{"day"}
(and a base date of @code{"1 Jan 1900"}) will result in turns
@code{"1 Jan 1900"}, @code{"2 Jan 1900"}, etc,
while a date unit of @code{"year"}
will yield just @code{"1900"}, @code{"1901"}, and so forth.
If the numeric calendar is in use, then the time measure @code{"day"}
will yield @code{"day 1"}, @code{"day 2"}, etc.

(Eventually it is intended to support multiples of units, such as
"2 day", which will just display every other day as a turn.)
@end deffn

@deffn Symbol @code{usual}
@end deffn

@deffn GlobalVariable @code{calendar-part-names} {((n1 n2 name)@dots{})}
This variable lists the name of each season and the turns within a year
for which it is appropriate.
A twelve-month year with four seasons could be
@example
((0 2 "winter") (3 5 "spring") (6 8 "summer") (9 11 "autumn"))
@end example
If any number ranges overlap, then the first match will be used,
while if a particular turn has no named season, then it will go
unnamed in the display.
Defaults to @code{()}.
@end deffn

@deffn GlobalVariable @code{initial-date}
This variable is the date, in the specified calendar system, of the first turn.
Defaults to @code{""}, which has the effect of setting the initial date
to be whatever the calendar does with turn number 1.
@end deffn

@deffn GlobalVariable @code{turn} n
This variable is the date of the current turn.
[written correctly?]
Defaults to @code{0}.
@end deffn

@deffn GlobalVariable @code{last-turn} n
This variable is the date, in the specified calendar system,
of the last turn.
Defaults to @code{-1}, which means that there is no limit on the number
of turns.
@end deffn

@deffn GlobalVariable @code{extra-turn-chance} n%
This variable is the chance that the game will go one more turn
after the @code{last-turn}.
@end deffn

@i{Xconq} is currently limited to games of 32,767 turns.

A game may also be limited in real time.

@deffn GlobalVariable @code{real-time-for-game} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-turn} seconds
@end deffn

@deffn GlobalVariable @code{real-time-per-side} seconds
@end deffn

@deffn GlobalVariable @code{elapsed-real-time} seconds
@end deffn

@section Miscellany

@deffn UnitTypeProperty @code{name-internal} str
Internally used type name.
@end deffn

@subsection Debugging

@deffn Form @code{print} value
This form prints to a console (or whatever the interface provides)
the object @var{value}, in GDL syntax.
@end deffn

@subsection AI Data

These are computed and used internally by AIs.

@deffn XXX @code{zzz-fr}
@end deffn

@deffn XXX @code{zzz-uaw}
@end deffn

@deffn XXX @code{zzz-dw}
@end deffn

@deffn XXX @code{zzz-ew}
@end deffn

@deffn XXX @code{zzz-mrs}
@end deffn

@deffn XXX @code{zzz-b}
@end deffn

@deffn XXX @code{zzz-bb}
@end deffn

@deffn XXX @code{zzz-transport}
@end deffn

@deffn XXX @code{zzz-c}
@end deffn

@deffn XXX @code{zzz-cm}
@end deffn

@deffn XXX @code{zzz-cc}
@end deffn

@deffn XXX @code{zzz-uh}
@end deffn

@deffn XXX @code{zzz-bw}
@end deffn

@deffn XXX @code{zzz-abt}
@end deffn

@deffn XXX @code{zzz-bhw}
@end deffn

@deffn XXX @code{zzz-bcw}
@end deffn